@opengsd/gsd-pi 1.3.0 → 1.4.0

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

@@ -19,7 +19,7 @@ import { setRuntimeKv, deleteRuntimeKv, } from "./db/runtime-kv.js";
 import { extractSection, getManifestStatus, splitFrontmatter, parseFrontmatterMap } from "./files.js";
 export { inlinePriorMilestoneSummary } from "./files.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
-import { gsdRoot, resolveMilestoneFile, resolveMilestonePath, resolveDir, milestonesDir, } from "./paths.js";
+import { gsdRoot, resolveMilestoneFile, resolveMilestonePath, resolveDir, milestonesDir, legacyMilestonesDir, isLegacyMilestonesLayout, canonicalPhaseDirName, } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { clearActivityLogState } from "./activity-log.js";
 import { synthesizeCrashRecovery, getDeepDiagnostic, readActiveMilestoneId, } from "./session-forensics.js";
@@ -27,7 +27,7 @@ import { writeLock, clearLock, clearStaleWorkerLock, readCrashLock, isLockProces
 import { acquireSessionLock, getSessionLockStatus, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
 import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences, loadEffectiveGSDPreferencesWithRegistry, resolveProfileAnchorProvider, getIsolationMode, resolveEffectiveUnitIsolationMode, } from "./preferences.js";
 import { playNotificationBell, sendDesktopNotification } from "./notifications.js";
-import { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, resolveCompactionThresholdPercent, shouldRerootStepSessionForContext, } from "./auto-budget.js";
+import { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, HARD_CONTEXT_REROOT_THRESHOLD_PERCENT, resolveCompactionThresholdPercent, shouldRerootStepSessionForContext, shouldWarnStepSessionForContext, } from "./auto-budget.js";
 import { markToolStart as _markToolStart, markToolEnd as _markToolEnd, getOldestInFlightToolAgeMs as _getOldestInFlightToolAgeMs, clearInFlightTools, isToolInvocationError, isQueuedUserMessageSkip, isDeterministicPolicyError, } from "./auto-tool-tracking.js";
 import { closeoutUnit } from "./auto-unit-closeout.js";
 import { selectAndApplyModel, resolveModelId, clearToolBaseline } from "./auto-model-selection.js";
@@ -369,7 +369,7 @@ function getEffectiveUnitIsolationMode(basePath) {
  * running suspiciously long (e.g., a Bash command hung because `&` kept stdout open).
  */
 // Re-export budget utilities for external consumers
-export { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, getContextPauseAction, resolveCompactionThresholdPercent, shouldRerootStepSessionForContext, } from "./auto-budget.js";
+export { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, getContextPauseAction, resolveCompactionThresholdPercent, shouldRerootStepSessionForContext, shouldWarnStepSessionForContext, } from "./auto-budget.js";
 function closeOutSignalInterruptedUnit(currentBasePath) {
     const currentUnit = s.currentUnit;
     if (!currentUnit)
@@ -904,9 +904,10 @@ export async function rerootCommandSession(cmdCtx, workspaceRoot) {
     }
 }
 /**
- * After a completed step-mode unit, reclaim context headroom when usage is at
- * or above the compaction threshold. Writes a context-mode snapshot first, then
- * re-roots the visible command session while leaving the NEXT progress surface.
+ * After a completed step-mode unit, warn when usage reaches the configurable
+ * soft context threshold. At the fixed hard boundary, write a context-mode
+ * snapshot and re-root the visible command session while leaving the NEXT
+ * progress surface.
  */
 export async function maybeRerootStepSessionForHighContext(ctx, workspaceRoot, cmdCtx, originalBasePath) {
     if (!cmdCtx)
@@ -915,18 +916,24 @@ export async function maybeRerootStepSessionForHighContext(ctx, workspaceRoot, c
     const { loadEffectiveGSDPreferences } = await import("./preferences.js");
     const prefs = loadEffectiveGSDPreferences(workspaceRoot);
     const compactionThreshold = prefs?.preferences.context_management?.compaction_threshold_percent;
-    if (!shouldRerootStepSessionForContext(contextPercent, compactionThreshold)) {
+    const shouldWarn = shouldWarnStepSessionForContext(contextPercent, compactionThreshold);
+    const shouldReroot = shouldRerootStepSessionForContext(contextPercent);
+    if (!shouldWarn && !shouldReroot) {
+        return { rerooted: false };
+    }
+    const displayPercent = contextPercent.toFixed(1);
+    const thresholdDisplay = resolveCompactionThresholdPercent(compactionThreshold).toFixed(0);
+    if (!shouldReroot) {
+        ctx.ui.notify(`Step complete — context at ${displayPercent}% (soft threshold: ${thresholdDisplay}%). Use /compact when convenient; continuing in this session is still safe.`, "info");
         return { rerooted: false };
     }
     const { resolveWorktreeProjectRoot } = await import("./worktree-root.js");
     const snapshotBase = resolveWorktreeProjectRoot(workspaceRoot, originalBasePath);
     const { writeContextModeCompactionSnapshot } = await import("./context-mode-snapshot.js");
     await writeContextModeCompactionSnapshot(snapshotBase);
-    const displayPercent = contextPercent.toFixed(1);
-    const thresholdDisplay = resolveCompactionThresholdPercent(compactionThreshold).toFixed(0);
     const result = await rerootCommandSession(cmdCtx, workspaceRoot);
     if (result.status === "ok") {
-        ctx.ui.notify(`Step complete — context at ${displayPercent}% (threshold: ${thresholdDisplay}%). Fresh session ready for /gsd next.`, "info");
+        ctx.ui.notify(`Step complete — context at ${displayPercent}% (hard threshold: ${HARD_CONTEXT_REROOT_THRESHOLD_PERCENT}%). Fresh session ready for /gsd next.`, "info");
         return { rerooted: true };
     }
     if (result.status === "cancelled") {
@@ -1545,7 +1552,7 @@ export function _selectStopAutoWorktreeExit(args) {
 /**
  * Pause auto-mode without destroying state. Context is preserved.
  * The user can interact with the agent, then `/gsd auto` resumes
- * from disk state. Called when the user presses Escape during auto-mode.
+ * from disk state. Called when the user presses Escape or runs `/gsd pause`.
  */
 export async function pauseAuto(ctx, _pi, _errorContext, options = {}) {
     if (!s.active)
@@ -1564,6 +1571,8 @@ export async function pauseAuto(ctx, _pi, _errorContext, options = {}) {
     ].filter((path) => Boolean(path)));
     s.active = false;
     s.paused = true;
+    if (options.abortActiveTurn && ctx && !ctx.isIdle())
+        ctx.abort();
     clearUnitTimeout();
     stopAutoCommandPolling();
     // Flush queued follow-up messages (#3512).
@@ -1771,7 +1780,7 @@ function buildLoopDeps(pi, ctx) {
         invalidateAllCaches,
         deriveState,
         rebuildState,
-        loadEffectiveGSDPreferences: () => loadEffectiveGSDPreferencesWithRegistry(ctx.modelRegistry, s.basePath || undefined, resolveProfileAnchorProvider(ctx.model?.provider, s.autoModeStartModel?.provider)),
+        loadEffectiveGSDPreferences: () => loadEffectiveGSDPreferencesWithRegistry(ctx.modelRegistry, s.basePath || undefined, resolveProfileAnchorProvider(ctx.model?.provider, s.autoModeStartModel?.provider), s.autoModeStartModel ? `${s.autoModeStartModel.provider}/${s.autoModeStartModel.id}` : undefined),
         // Pre-dispatch health gate
         preDispatchHealthGate,
         // Worktree state projection (ADR-016 — single Module Interface)
@@ -1899,7 +1908,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     // 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");
+        ctx.ui.notify("Recovered unfinished external state migration.", "info");
     }
     const unmergedStartMessage = await getUnmergedMilestoneBlockMessageForBase(base, "auto");
     if (unmergedStartMessage) {
@@ -2292,10 +2301,26 @@ export function ensurePreconditions(unitType, unitId, base, state) {
                 return;
             }
         }
-        const newDir = join(milestonesDir(base), mid);
-        mkdirSync(join(newDir, "slices"), { recursive: true });
+        // Layout-aware: if the legacy milestones/ dir exists, place the new milestone dir
+        // there (preserves the existing project layout). Otherwise use flat-phase phases/.
+        const legacyBase = legacyMilestonesDir(base);
+        const isLegacyLayout = isLegacyMilestonesLayout(base);
+        const targetBase = isLegacyLayout ? legacyBase : milestonesDir(base);
+        // Flat-phase: look up the milestone title to build the canonical NN-slug dir name
+        // (e.g. "01-foundation") that resolveMilestonePath will later find by prefix.
+        // Legacy layout keeps the raw milestone id (e.g. "M001").
+        const dirName = isLegacyLayout
+            ? mid
+            : canonicalPhaseDirName(mid, getMilestone(mid)?.title);
+        const newDir = join(targetBase, dirName);
+        // Legacy projects use a slices/ subdir; flat-phase uses top-level plan files (no slices/).
+        mkdirSync(isLegacyLayout ? join(newDir, "slices") : newDir, { recursive: true });
     }
     if (sid !== undefined) {
+        const isLegacyLayout = isLegacyMilestonesLayout(base);
+        // Flat-phase: tasks are checkboxes in NN-MM-PLAN.md — no slices/ subdir needed.
+        if (!isLegacyLayout)
+            return;
         const mDirResolved = resolveMilestonePath(base, mid);
         if (mDirResolved) {
             const slicesDir = join(mDirResolved, "slices");

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

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

package/dist/resources/extensions/gsd/bootstrap/core-session-tools.js

@@ -0,0 +1,39 @@
+// Project/App: gsd-pi
+// File Purpose: Canonical core session tool surface shared by auto-mode scoping and loop guards.
+/** Base tools available during auto-mode execution before unit-specific GSD tools are added. */
+export const MINIMAL_AUTO_BASE_TOOL_NAMES = [
+    "ask_user_questions",
+    "bash",
+    "bg_shell",
+    "edit",
+    "find",
+    "glob",
+    "grep",
+    "fetch_page",
+    "search-the-web",
+    "ls",
+    "read",
+    "subagent",
+    "write",
+    "ToolSearch",
+];
+/** Tools excluded from the high per-turn loop-guard cap (strict or orchestration). */
+const NON_REPEATABLE_FROM_MINIMAL_BASE = new Set([
+    "ask_user_questions",
+    "subagent",
+    "ToolSearch",
+]);
+/** Additional core tools not in MINIMAL_AUTO_BASE but routinely multi-called per turn. */
+const EXTRA_INHERENTLY_REPEATABLE = [
+    "gsd_exec",
+    "multi_edit",
+    "todo_write",
+    "notebook_edit",
+    "search_and_read",
+];
+/** Core session tools that may be invoked many times per agent turn. */
+export const INHERENTLY_REPEATABLE_TOOL_NAMES = [
+    ...MINIMAL_AUTO_BASE_TOOL_NAMES.filter((name) => !NON_REPEATABLE_FROM_MINIMAL_BASE.has(name)),
+    ...EXTRA_INHERENTLY_REPEATABLE,
+];
+export const INHERENTLY_REPEATABLE_TOOL_SET = new Set(INHERENTLY_REPEATABLE_TOOL_NAMES);

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

@@ -2,6 +2,7 @@
 // File Purpose: Registers DB-backed GSD workflow tools and compatibility aliases.
 import { Type, StringEnum } from "@gsd/pi-ai";
 import { Text } from "@gsd/pi-tui";
+import { SUMMARY_SAVE_CONTENT_MAX_LENGTH } from "@opengsd/contracts";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { ensureDbOpen, resolveCtxCwd, resolveWorkflowToolBasePath } from "./dynamic-tools.js";
 import { importWorkflowExecutorsModule } from "../workflow-mcp.js";
@@ -373,13 +374,17 @@ export function registerDbTools(pi) {
             "Root-level artifact paths are PROJECT.md, PROJECT-DRAFT.md, REQUIREMENTS.md, and REQUIREMENTS-DRAFT.md.",
             "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT.",
             "Use CONTEXT-DRAFT for incremental draft persistence; use CONTEXT for the final milestone context after depth verification.",
+            `Keep each content payload under ${SUMMARY_SAVE_CONTENT_MAX_LENGTH} characters; save large context incrementally with CONTEXT-DRAFT/PROJECT-DRAFT/REQUIREMENTS-DRAFT instead of one oversized call.`,
         ],
         parameters: Type.Object({
             milestone_id: Type.Optional(Type.String({ description: "Milestone ID (e.g. M001). Omit only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT artifacts." })),
             slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
             task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
             artifact_type: StringEnum(["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT", "CONTEXT-DRAFT", "PROJECT", "PROJECT-DRAFT", "REQUIREMENTS", "REQUIREMENTS-DRAFT"], { description: "Artifact type to save" }),
-            content: Type.String({ description: "The full markdown content of the artifact" }),
+            content: Type.String({
+                description: `The full markdown content of the artifact. Maximum ${SUMMARY_SAVE_CONTENT_MAX_LENGTH} characters per save.`,
+                maxLength: SUMMARY_SAVE_CONTENT_MAX_LENGTH,
+            }),
         }),
         execute: summarySaveExecute,
         renderCall(args, theme) {
@@ -649,8 +654,9 @@ export function registerDbTools(pi) {
         promptSnippet: "Plan a slice via DB write + PLAN render + cache invalidation",
         promptGuidelines: [
             "Use gsd_plan_slice for slice planning instead of writing S##-PLAN.md or task PLAN files directly.",
-            "Keep parameters flat and provide the full slice planning payload, including tasks.",
-            "The tool validates input, requires an existing parent slice, writes slice/task planning data, renders PLAN.md and task plan files from DB, and clears both state and parse caches after success.",
+            "For incremental planning, call gsd_plan_slice with slice metadata only, then call gsd_plan_task once per task.",
+            "When tasks is omitted or empty, the tool writes only slice planning metadata and preserves existing tasks.",
+            "When tasks is non-empty, the tool validates input, requires an existing parent slice, writes slice/task planning data, renders PLAN.md and task plan files from DB, and clears both state and parse caches after success.",
             "Use the canonical name gsd_plan_slice; gsd_slice_plan is only an alias.",
         ],
         parameters: Type.Object({
@@ -658,7 +664,7 @@ export function registerDbTools(pi) {
             milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
             sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
             goal: Type.String({ description: "Slice goal" }),
-            tasks: Type.Array(Type.Object({
+            tasks: Type.Optional(Type.Array(Type.Object({
                 taskId: Type.String({ description: "Task ID (e.g. T01)" }),
                 title: Type.String({ description: "Task title" }),
                 description: Type.String({ description: "Task description / steps block" }),
@@ -668,7 +674,7 @@ export function registerDbTools(pi) {
                 inputs: Type.Array(Type.String(), { description: "Array<string> of input files or references; pass [\"path\"] or [], never a single string" }),
                 expectedOutput: Type.Array(Type.String(), { description: "Array<string> of files this task creates or overwrites; pass [\"path\"] or [], never prose or a single string" }),
                 observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
-            }), { description: "Planned tasks for the slice" }),
+            }), { description: "Optional full task replacement for the slice. Omit for incremental planning, then call gsd_plan_task once per task." })),
             // ── Enrichment metadata (optional — defaults to empty) ────────────
             successCriteria: Type.Optional(Type.String({ description: "Slice success criteria block" })),
             proofLevel: Type.Optional(Type.String({ description: "Slice proof level" })),

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

@@ -60,6 +60,7 @@ export function registerExecTools(pi) {
             return executeUatExec(params, {
                 baseDir,
                 preferences: await loadContextModePreferences(baseDir),
+                signal: _signal,
             });
         },
     });
@@ -99,6 +100,7 @@ export function registerExecTools(pi) {
             return executeGsdExec(params, {
                 baseDir,
                 preferences: await loadContextModePreferences(baseDir),
+                signal: _signal,
             });
         },
     });

package/dist/resources/extensions/gsd/bootstrap/fallback-continuation.js

@@ -0,0 +1,25 @@
+// gsd-pi + src/resources/extensions/gsd/bootstrap/fallback-continuation.ts - Dispatches the post-fallback-switch continuation on a fresh turn.
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+/**
+ * Dispatch the post-fallback continuation on a *fresh* turn after the current
+ * run settles.
+ *
+ * #804: At `agent_end` time the agent's run is still tearing down — its
+ * `isStreaming` flag stays `true` until `finishRun()` clears it in the `finally`
+ * block that fires *after* the awaited `agent_end` listeners return (see
+ * pi-agent-core/src/agent.ts processEvents comment). A synchronous
+ * `sendMessage({ triggerTurn: true, deliverAs: "steer" })` from inside that
+ * listener is therefore routed down the `isStreaming` branch and queued as a
+ * steering message against the turn that just errored out — which is never
+ * consumed, so the fallback model is selected but no new turn ever starts (the
+ * reported symptom: "switched but work stays stopped").
+ *
+ * Deferring to a macrotask lets `finishRun()` flip `isStreaming` to `false`
+ * first; the plain `triggerTurn` (no `deliverAs`) then dispatches a fresh turn
+ * on the freshly-selected fallback model, mirroring the network-retry path.
+ */
+export function scheduleFallbackContinuation(pi) {
+    setTimeout(() => {
+        pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
+    }, 0);
+}

package/dist/resources/extensions/gsd/bootstrap/register-extension.js

@@ -14,6 +14,7 @@ import { registerShortcuts } from "./register-shortcuts.js";
 import { writeCrashLog } from "./crash-log.js";
 import { logWarning, isGsdExtensionStderrEnabled } from "../workflow-logger.js";
 import { UNIT_TOOL_CONTRACTS } from "../unit-tool-contracts.js";
+import { installManifestFlushOnProcessTeardown } from "../workflow-manifest.js";
 // Static import so cmux event listeners are registered synchronously during
 // extension bootstrap. Prior implementation used `void import().then()` which
 // queued listener registration as a microtask — any CMUX_CHANNELS emit fired
@@ -127,10 +128,30 @@ export function installEpipeGuard() {
         process.on("unhandledRejection", _gsdRejectionGuard);
     }
 }
+/**
+ * Assert that critical GSD workflow tools were registered.
+ *
+ * During extension loading, getAllTools() is a throwing stub
+ * ("Extension runtime not initialized") that only becomes real after
+ * runner.bindCore(). Calling it here used to throw, propagating to index.ts's
+ * catch and firing "Extension setup partially failed" — which, under Claude
+ * Code CLI, left the model's tool surface incomplete and trapped units in a
+ * finalize-retry loop. Tolerate the pre-bind throw and defer the real check to
+ * the first before_agent_start (where applyMinimalGsdToolSurface already
+ * re-reads the registered surface post-bind).
+ */
 function assertCriticalGsdWorkflowToolsRegistered(pi) {
     if (typeof pi.getAllTools !== "function")
         return;
-    const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+    let registered;
+    try {
+        registered = new Set(pi.getAllTools().map((tool) => tool.name));
+    }
+    catch {
+        // Pre-bind runtime: getAllTools() is not yet wired. The critical-tools
+        // invariant is re-checked post-bind during the first before_agent_start.
+        return;
+    }
     const missing = CRITICAL_GSD_WORKFLOW_TOOL_NAMES.filter((toolName) => !registered.has(toolName));
     if (missing.length === 0)
         return;
@@ -157,6 +178,7 @@ export function registerGsdExtension(pi) {
         process.stderr.write(`[gsd] Failed to bootstrap hook-emitter bridge: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
     });
     installEpipeGuard();
+    installManifestFlushOnProcessTeardown();
     // Ecosystem handlers captured by the GSDExtensionAPI wrapper for the
     // GSD-owned `before_agent_start` dispatch step (#3338).
     const ecosystemHandlers = [];