gsd-pi 2.76.0 → 2.77.0-dev.1594b263e

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

@@ -1,5 +1,6 @@
 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";
@@ -8,9 +9,18 @@ import { resolveModelId } from "../auto-model-selection.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
 import { resumeAutoAfterProviderDelay } from "./provider-error-resume.js";
 import { classifyError, createRetryState, resetRetryState, isTransient, } 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.
  * Called by provider-error-resume.ts before startAuto() — without this, the
@@ -48,10 +58,32 @@ async function pauseTransientWithBackoff(cls, pi, ctx, errorDetail, isRateLimit)
     });
 }
 export async function handleAgentEnd(pi, event, ctx) {
+    // #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())
@@ -106,6 +138,81 @@ export async function handleAgentEnd(pi, event, ctx) {
         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);
+        // ── 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 = 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,
@@ -210,6 +317,9 @@ export async function handleAgentEnd(pi, event, ctx) {
     // ── 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) {

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

@@ -19,6 +19,18 @@ function registerAlias(pi, toolDef, aliasName, canonicalName) {
         promptGuidelines: [`Alias for ${canonicalName} — prefer the canonical name.`],
     });
 }
+/**
+ * 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) {
+    return result?.details ?? result?.structuredContent;
+}
 export function registerDbTools(pi) {
     // ─── gsd_decision_save (formerly gsd_save_decision) ─────────────────────
     const decisionSaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
@@ -92,7 +104,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
         renderResult(result, _options, theme) {
-            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);
             }
@@ -175,7 +187,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
         renderResult(result, _options, theme) {
-            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);
             }
@@ -255,7 +267,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
         renderResult(result, _options, theme) {
-            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);
             }
@@ -301,7 +313,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
         renderResult(result, _options, theme) {
-            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);
             }
@@ -382,7 +394,7 @@ export function registerDbTools(pi) {
             return new Text(theme.fg("toolTitle", theme.bold("milestone_generate_id")), 0, 0);
         },
         renderResult(result, _options, theme) {
-            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);
             }
@@ -450,6 +462,9 @@ export function registerDbTools(pi) {
             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,
     };
@@ -491,6 +506,9 @@ export function registerDbTools(pi) {
             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,
     };
@@ -557,6 +575,9 @@ export function registerDbTools(pi) {
             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,
     };
@@ -616,6 +637,9 @@ export function registerDbTools(pi) {
                 }),
                 Type.String({ description: "Fallback: verification summary string" }),
             ]), { 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,
     };
@@ -693,6 +717,9 @@ export function registerDbTools(pi) {
                 }),
                 Type.String({ description: "Fallback: slice ID string" }),
             ]), { 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,
     };
@@ -814,6 +841,9 @@ export function registerDbTools(pi) {
             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,
     };
@@ -885,6 +915,9 @@ export function registerDbTools(pi) {
                 expectedOutput: Type.Array(Type.String(), { description: "Expected output files or artifacts" }),
             }), { 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,
     };
@@ -929,11 +962,199 @@ export function registerDbTools(pi) {
                 }), { description: "New slices to add" }),
                 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,
     };
     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, params, _signal, _onUpdate, _ctx) => {
+        const dbAvailable = await ensureDbOpen();
+        if (!dbAvailable) {
+            return {
+                content: [{ type: "text", text: "Error: GSD database is not available. Cannot reopen task." }],
+                details: { operation: "reopen_task", error: "db_unavailable" },
+            };
+        }
+        try {
+            const { handleReopenTask } = await import("../tools/reopen-task.js");
+            const result = await handleReopenTask(params, process.cwd());
+            if ("error" in result) {
+                return {
+                    content: [{ type: "text", text: `Error reopening task: ${result.error}` }],
+                    details: { operation: "reopen_task", error: result.error },
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Reopened task ${result.taskId} (${result.sliceId}/${result.milestoneId})` }],
+                details: {
+                    operation: "reopen_task",
+                    milestoneId: result.milestoneId,
+                    sliceId: result.sliceId,
+                    taskId: result.taskId,
+                },
+            };
+        }
+        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", text: `Error reopening task: ${msg}` }],
+                details: { operation: "reopen_task", error: msg },
+            };
+        }
+    };
+    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, params, _signal, _onUpdate, _ctx) => {
+        const dbAvailable = await ensureDbOpen();
+        if (!dbAvailable) {
+            return {
+                content: [{ type: "text", text: "Error: GSD database is not available. Cannot reopen slice." }],
+                details: { operation: "reopen_slice", error: "db_unavailable" },
+            };
+        }
+        try {
+            const { handleReopenSlice } = await import("../tools/reopen-slice.js");
+            const result = await handleReopenSlice(params, process.cwd());
+            if ("error" in result) {
+                return {
+                    content: [{ type: "text", text: `Error reopening slice: ${result.error}` }],
+                    details: { operation: "reopen_slice", error: result.error },
+                };
+            }
+            return {
+                content: [{ type: "text", 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,
+                },
+            };
+        }
+        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", text: `Error reopening slice: ${msg}` }],
+                details: { operation: "reopen_slice", error: msg },
+            };
+        }
+    };
+    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, params, _signal, _onUpdate, _ctx) => {
+        const dbAvailable = await ensureDbOpen();
+        if (!dbAvailable) {
+            return {
+                content: [{ type: "text", text: "Error: GSD database is not available. Cannot reopen milestone." }],
+                details: { operation: "reopen_milestone", error: "db_unavailable" },
+            };
+        }
+        try {
+            const { handleReopenMilestone } = await import("../tools/reopen-milestone.js");
+            const result = await handleReopenMilestone(params, process.cwd());
+            if ("error" in result) {
+                return {
+                    content: [{ type: "text", text: `Error reopening milestone: ${result.error}` }],
+                    details: { operation: "reopen_milestone", error: result.error },
+                };
+            }
+            return {
+                content: [{ type: "text", 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,
+                },
+            };
+        }
+        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", text: `Error reopening milestone: ${msg}` }],
+                details: { operation: "reopen_milestone", error: msg },
+            };
+        }
+    };
+    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, params, _signal, _onUpdate, _ctx) => {
         return executeSaveGateResult(params, process.cwd());
@@ -967,13 +1188,31 @@ export function registerDbTools(pi) {
             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, _options, theme) {
-            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);
         },
     };
     pi.registerTool(saveGateResultTool);

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

@@ -0,0 +1,93 @@
+// GSD2 — Exec (context-mode) tool registration.
+//
+// Exposes the `gsd_exec` tool over MCP. Opt-in: disabled unless
+// `context_mode.enabled: true` is set in preferences.
+import { Type } from "@sinclair/typebox";
+import { executeGsdExec } from "../tools/exec-tool.js";
+import { executeExecSearch } from "../tools/exec-search-tool.js";
+import { executeResume } from "../tools/resume-tool.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { logWarning } from "../workflow-logger.js";
+export function registerExecTools(pi) {
+    pi.registerTool({
+        name: "gsd_exec",
+        label: "Exec (Sandboxed)",
+        description: "Run a short script (bash/node/python) in a subprocess. Full stdout/stderr persist to " +
+            ".gsd/exec/<id>.{stdout,stderr,meta.json}; only a short digest returns in context. Use " +
+            "this instead of reading many files or emitting large tool outputs — e.g. have the script " +
+            "count/grep/summarize and log the finding. Enabled by default; opt out via " +
+            "preferences.context_mode.enabled=false.",
+        promptSnippet: "Run a bash/node/python script in a sandbox; full output is saved to disk and only a digest returns",
+        promptGuidelines: [
+            "Prefer gsd_exec for analyses that would otherwise read >3 files or produce large tool output.",
+            "Write scripts that log the finding (counts, matches, summaries) rather than raw dumps.",
+            "The digest is the last ~300 chars of stdout — size your log output accordingly.",
+            "Need the full output? Read the stdout_path returned in details (file on local disk).",
+        ],
+        parameters: Type.Object({
+            runtime: Type.Union([Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")], { description: "Interpreter: bash (-c), node (-e), or python3 (-c)." }),
+            script: Type.String({ description: "Script body. Keep output small (log the finding, not the data)." }),
+            purpose: Type.Optional(Type.String({ description: "Short label recorded in meta.json for later review." })),
+            timeout_ms: Type.Optional(Type.Number({
+                description: "Per-invocation timeout (ms). Capped at 600000. Default from preferences.",
+                minimum: 1_000,
+                maximum: 600_000,
+            })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            let prefs = null;
+            try {
+                prefs = loadEffectiveGSDPreferences();
+            }
+            catch (err) {
+                logWarning("tool", `gsd_exec could not load preferences: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return executeGsdExec(params, {
+                baseDir: process.cwd(),
+                preferences: prefs?.preferences ?? null,
+            });
+        },
+    });
+    pi.registerTool({
+        name: "gsd_exec_search",
+        label: "Search gsd_exec History",
+        description: "List prior gsd_exec runs (most recent first) from .gsd/exec/*.meta.json. Useful for " +
+            "rediscovering the stdout_path of an earlier run without re-executing it. Read-only.",
+        promptSnippet: "Search prior gsd_exec runs by substring, runtime, or failing-only filter",
+        promptGuidelines: [
+            "Use this before re-running an expensive analysis — the prior run's stdout file may still answer.",
+            "The preview shows the trailing ~300 chars of stdout; read stdout_path for the full transcript.",
+        ],
+        parameters: Type.Object({
+            query: Type.Optional(Type.String({ description: "Substring matched against id and purpose (case-insensitive)." })),
+            runtime: Type.Optional(Type.Union([Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")], {
+                description: "Restrict to one runtime.",
+            })),
+            failing_only: Type.Optional(Type.Boolean({ description: "Only non-zero exit codes and timeouts." })),
+            limit: Type.Optional(Type.Number({ description: "Max results (default 20, cap 200)", minimum: 1, maximum: 200 })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            return executeExecSearch(params, {
+                baseDir: process.cwd(),
+            });
+        },
+    });
+    pi.registerTool({
+        name: "gsd_resume",
+        label: "Resume (Read Snapshot)",
+        description: "Return the contents of .gsd/last-snapshot.md — a ≤2 KB digest of top memories, recent " +
+            "gsd_exec runs, and active context, written automatically on session_before_compact. Use " +
+            "this after compaction or session resume to re-orient quickly.",
+        promptSnippet: "Read the pre-compaction snapshot to re-orient after context loss",
+        promptGuidelines: [
+            "Call this right after a session resumes if you feel you've lost durable context.",
+            "The snapshot is a summary — use memory_query or gsd_exec_search for detail.",
+        ],
+        parameters: Type.Object({}),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            return executeResume(params, {
+                baseDir: process.cwd(),
+            });
+        },
+    });
+}

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

@@ -34,6 +34,9 @@ export function registerMemoryTools(pi) {
             confidence: Type.Optional(Type.Number({ description: "0.1–0.99, default 0.8", minimum: 0.1, maximum: 0.99 })),
             tags: Type.Optional(Type.Array(Type.String(), { description: "Free-form tags (reserved for future use)" })),
             scope: Type.Optional(Type.String({ description: "Scope name (reserved for future use; defaults to project)" })),
+            structuredFields: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
+                description: "Optional structured payload preserved alongside content (ADR-013). Use for decisions to retain scope/decision/choice/rationale/made_by/revisable. Omit for plain captures.",
+            })),
         }),
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
             const ok = await ensureDbOpen();

package/dist/resources/extensions/gsd/bootstrap/provider-error-resume.js

@@ -1,8 +1,8 @@
 import { getAutoDashboardData, startAuto } from "../auto.js";
 import { resetTransientRetryState } from "./agent-end-recovery.js";
-import { resetSessionTimeoutState } from "../auto/phases.js";
 const defaultDeps = {
     getSnapshot: () => getAutoDashboardData(),
+    resetTransientRetryState,
     startAuto,
 };
 export async function resumeAutoAfterProviderDelay(pi, ctx, deps = defaultDeps) {
@@ -15,11 +15,10 @@ export async function resumeAutoAfterProviderDelay(pi, ctx, deps = defaultDeps)
         ctx.ui.notify("Provider error recovery delay elapsed, but no paused auto-mode base path was available. Leaving auto-mode paused.", "warning");
         return "missing-base";
     }
-    // Reset retry counters before restarting — without this, counters
-    // accumulate across pause/resume cycles and permanently lock out
-    // auto-resume after their respective MAX thresholds.
-    resetTransientRetryState();
-    resetSessionTimeoutState();
+    // Reset provider-error retry state before restarting. Session-creation
+    // timeout state intentionally survives delayed resumes so the bounded
+    // auto-resume limit cannot be reset into an infinite pause/resume loop.
+    deps.resetTransientRetryState();
     await deps.startAuto(ctx, pi, snapshot.basePath, false, { step: snapshot.stepMode });
     return "resumed";
 }