gsd-pi 2.75.0 → 2.76.0-dev.4100bd590

package/dist/resources/extensions/gsd/auto.js

@@ -45,12 +45,14 @@ import { atomicWriteSync } from "./atomic-write.js";
 import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, } from "./worktree.js";
 import { GitServiceImpl } from "./git-service.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
-import { createAutoWorktree, enterAutoWorktree, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, syncWorktreeStateBack, syncProjectRootToWorktree, checkResourcesStale, escapeStaleWorktree, } from "./auto-worktree.js";
+import { createAutoWorktree, enterAutoWorktree, enterBranchModeForMilestone, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, syncWorktreeStateBack, syncProjectRootToWorktree, checkResourcesStale, escapeStaleWorktree, } from "./auto-worktree.js";
 import { pruneQueueOrder } from "./queue-order.js";
+import { startCommandPolling as _startCommandPolling, isRemoteConfigured } from "../remote-questions/manager.js";
 import { debugLog, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
 import { reconcileMergeState, } from "./auto-recovery.js";
 import { resolveDispatch, DISPATCH_RULES } from "./auto-dispatch.js";
 import { getErrorMessage } from "./error-utils.js";
+import { recoverFailedMigration } from "./migrate-external.js";
 import { initRegistry, convertDispatchRules } from "./rule-registry.js";
 import { emitJournalEvent as _emitJournalEvent } from "./journal.js";
 import { updateProgressWidget as _updateProgressWidget, updateSliceProgressCache, clearSliceProgressCache, hideFooter, } from "./auto-dashboard.js";
@@ -64,7 +66,7 @@ import { runPostUnitVerification } from "./auto-verification.js";
 import { autoCommitUnit, postUnitPreVerification, postUnitPostVerification, } from "./auto-post-unit.js";
 import { bootstrapAutoSession, openProjectDbIfPresent } from "./auto-start.js";
 import { initHealthWidget } from "./health-widget.js";
-import { autoLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto-loop.js";
+import { runLegacyAutoLoop, runUokKernelLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto-loop.js";
 import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { WorktreeResolver, } from "./worktree-resolver.js";
@@ -142,6 +144,7 @@ export function startAutoDetached(ctx, pi, base, verboseMode, options) {
         debugLog("auto-start-failed", { error: message });
     });
 }
+/** Returns true if the project is configured for `isolation:worktree` mode. */
 export function shouldUseWorktreeIsolation() {
     const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
     if (prefs?.isolation === "worktree")
@@ -185,6 +188,26 @@ function deregisterSigtermHandler() {
     _deregisterSigtermHandler(s.sigtermHandler);
     s.sigtermHandler = null;
 }
+/**
+ * Wrapper: start background command polling for the configured remote channel
+ * (currently Telegram only). Stores the cleanup function on the session so
+ * every exit path can stop the interval via stopCommandPolling().
+ * No-op when no remote channel is configured.
+ */
+function startAutoCommandPolling(basePath) {
+    if (!isRemoteConfigured())
+        return;
+    // Clear any existing interval before starting a new one (e.g. resume path).
+    stopAutoCommandPolling();
+    s.commandPollingCleanup = _startCommandPolling(basePath);
+}
+/** Wrapper: stop background command polling and clear the stored cleanup. */
+function stopAutoCommandPolling() {
+    if (s.commandPollingCleanup) {
+        s.commandPollingCleanup();
+        s.commandPollingCleanup = null;
+    }
+}
 export function getAutoDashboardData() {
     const ledger = getLedger();
     const totals = ledger ? getProjectTotals(ledger.units) : null;
@@ -248,6 +271,14 @@ export function getActiveRunDir() {
 export function getAutoModeStartModel() {
     return s.autoModeStartModel;
 }
+/**
+ * Update the dashboard-facing dispatched model label.
+ * Used when runtime recovery switches models mid-unit (e.g. provider fallback)
+ * so the AUTO box reflects the active model immediately.
+ */
+export function setCurrentDispatchedModelId(model) {
+    s.currentDispatchedModelId = model ? `${model.provider}/${model.id}` : null;
+}
 // Tool tracking — delegates to auto-tool-tracking.ts
 export function markToolStart(toolCallId, toolName) {
     _markToolStart(toolCallId, s.active, toolName);
@@ -392,6 +423,7 @@ function handleLostSessionLock(ctx, lockStatus) {
     s.paused = false;
     deactivateGSD();
     clearUnitTimeout();
+    stopAutoCommandPolling();
     restoreProjectRootEnv();
     restoreMilestoneLockEnv();
     deregisterSigtermHandler();
@@ -427,6 +459,7 @@ function cleanupAfterLoopExit(ctx) {
     s.active = false;
     deactivateGSD();
     clearUnitTimeout();
+    stopAutoCommandPolling();
     restoreProjectRootEnv();
     restoreMilestoneLockEnv();
     // Clear crash lock and release session lock so the next `/gsd next` does
@@ -471,6 +504,7 @@ export async function stopAuto(ctx, pi, reason) {
         // ── Step 1: Timers and locks ──
         try {
             clearUnitTimeout();
+            stopAutoCommandPolling();
             if (lockBase())
                 clearLock(lockBase());
             if (lockBase())
@@ -724,6 +758,7 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
     if (!s.active)
         return;
     clearUnitTimeout();
+    stopAutoCommandPolling();
     // Flush queued follow-up messages (#3512).
     // Late async notifications (async_job_result, gsd-auto-wrapup) can trigger
     // extra LLM turns after pause. Flush them the same way run-unit.ts does.
@@ -814,6 +849,7 @@ function buildResolverDeps() {
         teardownAutoWorktree,
         createAutoWorktree,
         enterAutoWorktree,
+        enterBranchModeForMilestone,
         getAutoWorktreePath,
         autoCommitCurrentBranch,
         getCurrentBranch,
@@ -941,6 +977,11 @@ function buildLoopDeps() {
         emitJournalEvent: (entry) => _emitJournalEvent(s.basePath, entry),
     };
 }
+/**
+ * Start auto-mode. Handles both fresh-start and resume paths, sets up session
+ * state, enters the milestone worktree or branch, and dispatches the first unit.
+ * No-ops if auto-mode is already active.
+ */
 export async function startAuto(ctx, pi, base, verboseMode, options) {
     if (s.active) {
         debugLog("startAuto", { phase: "already-active", skipping: true });
@@ -956,6 +997,12 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     }
     // Escape stale worktree cwd from a previous milestone (#608).
     base = escapeStaleWorktree(base);
+    // Heal .gsd.migrating before any branching — covers both fresh-start and
+    // resume paths (#4416). The matching call in auto-start.ts covers the
+    // bootstrap-only path; this call ensures the resume path is also protected.
+    if (recoverFailedMigration(base)) {
+        ctx.ui.notify("Recovered unfinished migration (.gsd.migrating → .gsd).", "info");
+    }
     const freshStartAssessment = interruptedAssessment
         ?? await assessInterruptedSession(base);
     if (freshStartAssessment.classification === "running") {
@@ -1112,9 +1159,9 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
             const level = to === "red" ? "error" : to === "yellow" ? "warning" : "info";
             ctx.ui.notify(summary, level);
         });
-        // ── Auto-worktree: re-enter worktree on resume ──
+        // ── Auto-worktree / branch-mode: re-enter on resume ──
         if (s.currentMilestoneId &&
-            shouldUseWorktreeIsolation() &&
+            getIsolationMode() !== "none" &&
             s.originalBasePath &&
             !isInAutoWorktree(s.basePath) &&
             !detectWorktreeName(s.basePath) &&
@@ -1179,12 +1226,14 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown");
         logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
         captureProjectRootEnv(s.originalBasePath || s.basePath);
+        startAutoCommandPolling(s.basePath);
         await runAutoLoopWithUok({
             ctx,
             pi,
             s,
             deps: buildLoopDeps(),
-            runLegacyLoop: autoLoop,
+            runKernelLoop: runUokKernelLoop,
+            runLegacyLoop: runLegacyAutoLoop,
         });
         cleanupAfterLoopExit(ctx);
         return;
@@ -1208,35 +1257,18 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         logWarning("engine", `cmux sync failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
     logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
+    startAutoCommandPolling(s.basePath);
     // Dispatch the first unit
     await runAutoLoopWithUok({
         ctx,
         pi,
         s,
         deps: buildLoopDeps(),
-        runLegacyLoop: autoLoop,
+        runKernelLoop: runUokKernelLoop,
+        runLegacyLoop: runLegacyAutoLoop,
     });
     cleanupAfterLoopExit(ctx);
 }
-// ─── Agent End Handler ────────────────────────────────────────────────────────
-/**
- * Deprecated thin wrapper — kept as export for backward compatibility.
- * The actual agent_end processing now happens via resolveAgentEnd() in auto-loop.ts,
- * which is called directly from index.ts. The autoLoop() while loop handles all
- * post-unit processing (verification, hooks, dispatch) that this function used to do.
- *
- * If called by straggler code, it simply resolves the pending promise so the loop
- * can continue.
- */
-export async function handleAgentEnd(ctx, pi) {
-    if (!s.active || !s.cmdCtx) {
-        // Even when inactive, resolve any pending promise so the loop is unblocked.
-        resolveAgentEndCancelled();
-        return;
-    }
-    clearUnitTimeout();
-    resolveAgentEnd({ messages: [] });
-}
 // describeNextUnit is imported from auto-dashboard.ts and re-exported
 export { describeNextUnit } from "./auto-dashboard.js";
 /** Thin wrapper: delegates to auto-dashboard.ts, passing state accessors. */

package/dist/resources/extensions/gsd/blocked-models.js

@@ -0,0 +1,68 @@
+// GSD — Persistent per-project blocklist of provider/model pairs that the
+// provider has rejected at request time for account entitlement reasons.
+//
+// Lives at `.gsd/runtime/blocked-models.json` so the block survives /gsd auto
+// restarts.  Auto-mode model selection skips blocked entries; agent-end
+// recovery adds entries when a runtime rejection is classified as
+// `unsupported-model`.  See issue #4513.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { gsdRoot } from "./paths.js";
+import { withFileLockSync } from "./file-lock.js";
+function blockedModelsPath(basePath) {
+    return join(gsdRoot(basePath), "runtime", "blocked-models.json");
+}
+function modelKey(provider, id) {
+    return `${provider.toLowerCase()}/${id.toLowerCase()}`;
+}
+function readFileSafe(path) {
+    if (!existsSync(path))
+        return { version: 1, blocked: [] };
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.blocked)) {
+            return { version: 1, blocked: [] };
+        }
+        const blocked = parsed.blocked.filter((e) => !!e && typeof e.provider === "string" && typeof e.id === "string");
+        return { version: 1, blocked };
+    }
+    catch {
+        // Corrupted JSON: treat as empty so a bad file never blocks dispatch.
+        return { version: 1, blocked: [] };
+    }
+}
+export function loadBlockedModels(basePath) {
+    return readFileSafe(blockedModelsPath(basePath)).blocked;
+}
+export function isModelBlocked(basePath, provider, id) {
+    if (!provider || !id)
+        return false;
+    const target = modelKey(provider, id);
+    return loadBlockedModels(basePath).some((e) => modelKey(e.provider, e.id) === target);
+}
+export function blockModel(basePath, provider, id, reason) {
+    const path = blockedModelsPath(basePath);
+    mkdirSync(dirname(path), { recursive: true });
+    // Ensure the file exists before we try to lock it — proper-lockfile requires
+    // the target path to exist (file-lock.ts falls through to an unlocked call
+    // otherwise).
+    if (!existsSync(path)) {
+        writeFileSync(path, JSON.stringify({ version: 1, blocked: [] }, null, 2) + "\n", "utf-8");
+    }
+    withFileLockSync(path, () => {
+        const current = readFileSafe(path);
+        const target = modelKey(provider, id);
+        if (current.blocked.some((e) => modelKey(e.provider, e.id) === target)) {
+            return;
+        }
+        const next = {
+            version: 1,
+            blocked: [
+                ...current.blocked,
+                { provider, id, reason, blockedAt: Date.now() },
+            ],
+        };
+        writeFileSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
+    });
+}

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

@@ -1,6 +1,6 @@
 import { logWarning } from "../workflow-logger.js";
 import { checkAutoStartAfterDiscuss } from "../guided-flow.js";
-import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto } from "../auto.js";
+import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto, setCurrentDispatchedModelId } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
 import { isSessionSwitchInFlight, resolveAgentEnd } from "../auto-loop.js";
@@ -8,6 +8,7 @@ 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;
@@ -106,26 +107,86 @@ 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);
-        // ── 1b. Defer to Core RetryHandler for transient errors ─────────────
-        // The Core RetryHandler (agent-session.ts) processes retryable errors
-        // AFTER this extension handler, in the same _processAgentEvent() call.
-        // For transient errors (overloaded, rate limit, server), the Core will
-        // retry in-context — same session, same conversation — which is strictly
-        // better than our Layer 2 pause+resume (which creates a new session).
-        //
-        // If we react here AND the Core also retries, we race: pauseAuto tears
-        // down the session while agent.continue() starts a new turn.
-        //
-        // Solution: Do nothing for transient errors. The Core RetryHandler
-        // runs next in _processAgentEvent and will either:
-        //   a) Retry successfully → new agent_end (success) → we see it next time
-        //   b) Exhaust retries → the agent stays idle, autoLoop's unit timeout
-        //      or stuck detection handles it
-        //
-        // We do NOT call resolveAgentEnd here — that would unblock autoLoop
-        // prematurely while the Core is still retrying in the same session.
-        // We do NOT call pauseAuto — that would tear down the session.
-        if (isTransient(cls)) {
+        // ── 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,
+        // but let rate-limit continue into model fallback logic below (#4373).
+        if (isTransient(cls) && cls.kind !== "rate-limit") {
             return;
         }
         // Cap rate-limit backoff for CLI-style providers (openai-codex, google-gemini-cli)
@@ -177,6 +238,7 @@ export async function handleAgentEnd(pi, event, ctx) {
                         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;
@@ -193,6 +255,7 @@ export async function handleAgentEnd(pi, event, ctx) {
                     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");

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

@@ -421,10 +421,14 @@ export function registerDbTools(pi) {
                 depends: Type.Array(Type.String(), { description: "Slice dependency IDs" }),
                 demo: Type.String({ description: "Roadmap demo text / After this" }),
                 goal: Type.String({ description: "Slice goal" }),
-                successCriteria: Type.String({ description: "Slice success criteria block" }),
-                proofLevel: Type.String({ description: "Slice proof level" }),
-                integrationClosure: Type.String({ description: "Slice integration closure" }),
-                observabilityImpact: Type.String({ description: "Slice observability impact" }),
+                // ADR-011: heavy planning fields are optional for sketch slices; required for full slices.
+                successCriteria: Type.Optional(Type.String({ description: "Slice success criteria block (required for full slices; omit for sketches)" })),
+                proofLevel: Type.Optional(Type.String({ description: "Slice proof level (required for full slices; omit for sketches)" })),
+                integrationClosure: Type.Optional(Type.String({ description: "Slice integration closure (required for full slices; omit for sketches)" })),
+                observabilityImpact: Type.Optional(Type.String({ description: "Slice observability impact (required for full slices; omit for sketches)" })),
+                // ADR-011 sketch-then-refine fields.
+                isSketch: Type.Optional(Type.Boolean({ description: "ADR-011: true marks this slice as a sketch awaiting refine-slice expansion" })),
+                sketchScope: Type.Optional(Type.String({ description: "ADR-011: 2–3 sentence scope boundary, required when isSketch=true" })),
             }), { description: "Planned slices for the milestone" }),
             // ── Enrichment metadata (optional — defaults to empty) ────────────
             status: Type.Optional(Type.String({ description: "Milestone status (defaults to active)" })),
@@ -589,6 +593,20 @@ export function registerDbTools(pi) {
             keyFiles: Type.Optional(Type.Array(Type.String(), { description: "List of key files created or modified" })),
             keyDecisions: Type.Optional(Type.Array(Type.String(), { description: "List of key decisions made during this task" })),
             blockerDiscovered: Type.Optional(Type.Boolean({ description: "Whether a plan-invalidating blocker was discovered" })),
+            // ADR-011 Phase 2: mid-execution escalation — agent asks the user to resolve an ambiguity.
+            escalation: Type.Optional(Type.Object({
+                question: Type.String({ description: "The question the user needs to answer — one clear sentence." }),
+                options: Type.Array(Type.Object({
+                    id: Type.String({ description: "Short id (e.g. 'A', 'B') used by /gsd escalate resolve." }),
+                    label: Type.String({ description: "One-line label." }),
+                    tradeoffs: Type.String({ description: "1-2 sentences on the tradeoffs of this option." }),
+                }), { minItems: 2, maxItems: 4, description: "2–4 options the user can choose between." }),
+                recommendation: Type.String({ description: "Option id the executor recommends." }),
+                recommendationRationale: Type.String({ description: "Why the recommendation — 1–2 sentences." }),
+                continueWithDefault: Type.Boolean({
+                    description: "When true, loop continues (artifact logged for later review). When false, auto-mode pauses until the user resolves via /gsd escalate resolve.",
+                }),
+            }, { description: "ADR-011 Phase 2: optional escalation payload. Only honored when phases.mid_execution_escalation is true." })),
             verificationEvidence: Type.Optional(Type.Array(Type.Union([
                 Type.Object({
                     command: Type.String({ description: "Verification command that was run" }),
@@ -690,28 +708,23 @@ export function registerDbTools(pi) {
             };
         }
         try {
-            const { getSlice, updateSliceStatus } = await import("../gsd-db.js");
+            const { handleSkipSlice } = await import("../tools/skip-slice.js");
             const { invalidateStateCache } = await import("../state.js");
-            const slice = getSlice(params.milestoneId, params.sliceId);
-            if (!slice) {
-                return {
-                    content: [{ type: "text", text: `Error: Slice ${params.sliceId} not found in milestone ${params.milestoneId}` }],
-                    details: { operation: "skip_slice", error: "slice_not_found" },
-                };
-            }
-            if (slice.status === "complete" || slice.status === "done") {
-                return {
-                    content: [{ type: "text", text: `Error: Slice ${params.sliceId} is already complete — cannot skip.` }],
-                    details: { operation: "skip_slice", error: "already_complete" },
-                };
-            }
-            if (slice.status === "skipped") {
+            const result = handleSkipSlice({
+                milestoneId: params.milestoneId,
+                sliceId: params.sliceId,
+                reason: params.reason,
+            });
+            if (result.error) {
                 return {
-                    content: [{ type: "text", text: `Slice ${params.sliceId} is already skipped.` }],
-                    details: { operation: "skip_slice", sliceId: params.sliceId, milestoneId: params.milestoneId },
+                    content: [{ type: "text", text: `Error: ${result.error}` }],
+                    details: {
+                        operation: "skip_slice",
+                        error: result.error,
+                        errorCode: result.errorCode ?? "skip_failed",
+                    },
                 };
             }
-            updateSliceStatus(params.milestoneId, params.sliceId, "skipped");
             invalidateStateCache();
             // Rebuild STATE.md so it reflects the skip immediately (#3477).
             // Without this, /gsd auto reads stale STATE.md and resumes the skipped slice.
@@ -723,13 +736,20 @@ export function registerDbTools(pi) {
             catch (err) {
                 logError("tool", `skip_slice rebuildState failed: ${err.message}`, { tool: "gsd_skip_slice" });
             }
+            const suffix = result.wasAlreadySkipped
+                ? result.tasksSkipped > 0
+                    ? ` (already skipped; cascaded ${result.tasksSkipped} leftover task(s) to skipped).`
+                    : " (already skipped; no pending tasks to cascade)."
+                : ` Cascaded ${result.tasksSkipped} task(s) to skipped. Auto-mode will advance past this slice.`;
             return {
-                content: [{ type: "text", text: `Skipped slice ${params.sliceId} (${params.milestoneId}). Reason: ${params.reason ?? "User-directed skip"}. Auto-mode will advance past this slice.` }],
+                content: [{ type: "text", text: `Skipped slice ${params.sliceId} (${params.milestoneId}). Reason: ${params.reason ?? "User-directed skip"}.${suffix}` }],
                 details: {
                     operation: "skip_slice",
                     sliceId: params.sliceId,
                     milestoneId: params.milestoneId,
                     reason: params.reason,
+                    tasksSkipped: result.tasksSkipped,
+                    wasAlreadySkipped: result.wasAlreadySkipped,
                 },
             };
         }
@@ -746,12 +766,14 @@ export function registerDbTools(pi) {
         name: "gsd_skip_slice",
         label: "Skip Slice",
         description: "Mark a slice as skipped so auto-mode advances past it without executing. " +
+            "Non-closed tasks within the slice are cascaded to skipped so milestone completion is not blocked by leftover pending tasks (#4375). " +
             "The slice data is preserved for reference. The state machine treats skipped slices like completed ones for dependency satisfaction.",
         promptSnippet: "Skip a GSD slice (mark as skipped, auto-mode will advance past it)",
         promptGuidelines: [
             "Use gsd_skip_slice when a slice should be bypassed — descoped, superseded, or no longer relevant.",
             "Cannot skip a slice that is already complete.",
             "Skipped slices satisfy downstream dependencies just like completed slices.",
+            "All pending/active tasks in the slice are cascaded to skipped; completed tasks are never downgraded.",
         ],
         parameters: Type.Object({
             sliceId: Type.String({ description: "Slice ID (e.g. S02)" }),