@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.5fc22c6f

package/src/resources/extensions/gsd/auto.ts

@@ -41,6 +41,7 @@ import {
 import { extractSection, getManifestStatus, splitFrontmatter, parseFrontmatterMap } from "./files.js";
 export { inlinePriorMilestoneSummary } from "./files.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
+
 import {
   gsdRoot,
   resolveMilestoneFile,
@@ -51,7 +52,10 @@ import {
   resolveTasksDir,
   resolveTaskFile,
   milestonesDir,
+  legacyMilestonesDir,
+  isLegacyMilestonesLayout,
   buildTaskFileName,
+  canonicalPhaseDirName,
 } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { clearActivityLogState } from "./activity-log.js";
@@ -93,8 +97,10 @@ import {
   getNewBudgetAlertLevel,
   getBudgetEnforcementAction,
   getContextPauseAction,
+  HARD_CONTEXT_REROOT_THRESHOLD_PERCENT,
   resolveCompactionThresholdPercent,
   shouldRerootStepSessionForContext,
+  shouldWarnStepSessionForContext,
 } from "./auto-budget.js";
 import {
   markToolStart as _markToolStart,
@@ -697,6 +703,7 @@ export {
   getContextPauseAction,
   resolveCompactionThresholdPercent,
   shouldRerootStepSessionForContext,
+  shouldWarnStepSessionForContext,
 } from "./auto-budget.js";
 
 function closeOutSignalInterruptedUnit(currentBasePath: string): void {
@@ -1044,6 +1051,12 @@ export function stopAutoRemote(projectRoot: string): {
  * The normal stop path stays SIGTERM-only so cooperative sessions can clean up;
  * this path is only for the explicit "Force start" action.
  */
+// Grace window between SIGTERM and SIGKILL so the target can run its cleanup
+// handler (lock release, DB snapshot flush, worktree teardown). Polled so a
+// process that exits early is not made to wait the full window.
+const FORCE_STOP_GRACE_MS = 3000;
+const FORCE_STOP_POLL_MS = 100;
+
 export function forceStopAutoRemote(projectRoot: string): {
   found: boolean;
   pid?: number;
@@ -1064,6 +1077,13 @@ export function forceStopAutoRemote(projectRoot: string): {
 
   try {
     process.kill(lock.pid, "SIGTERM");
+    // Poll for graceful exit before escalating. Synchronous sleep keeps this
+    // function sync for its callers (Atomics.wait times out with no notify).
+    const deadline = Date.now() + FORCE_STOP_GRACE_MS;
+    while (Date.now() < deadline) {
+      if (!isLockProcessAlive(lock)) break;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, FORCE_STOP_POLL_MS);
+    }
     if (isLockProcessAlive(lock)) {
       process.kill(lock.pid, "SIGKILL");
     }
@@ -1371,9 +1391,10 @@ export async function rerootCommandSession(
 }
 
 /**
- * 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: ExtensionContext,
@@ -1388,7 +1409,19 @@ export async function maybeRerootStepSessionForHighContext(
   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 as number).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 };
   }
 
@@ -1397,12 +1430,10 @@ export async function maybeRerootStepSessionForHighContext(
   const { writeContextModeCompactionSnapshot } = await import("./context-mode-snapshot.js");
   await writeContextModeCompactionSnapshot(snapshotBase);
 
-  const displayPercent = (contextPercent as number).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.`,
+      `Step complete — context at ${displayPercent}% (hard threshold: ${HARD_CONTEXT_REROOT_THRESHOLD_PERCENT}%). Fresh session ready for /gsd next.`,
       "info",
     );
     return { rerooted: true };
@@ -2098,7 +2129,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?: ExtensionContext,
@@ -2125,6 +2156,7 @@ export async function pauseAuto(
 
   s.active = false;
   s.paused = true;
+  if (options.abortActiveTurn && ctx && !ctx.isIdle()) ctx.abort();
   clearUnitTimeout();
   stopAutoCommandPolling();
 
@@ -2354,6 +2386,7 @@ function buildLoopDeps(pi: ExtensionAPI, ctx: ExtensionContext): LoopDeps {
         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
@@ -2513,7 +2546,7 @@ export async function startAuto(
   // 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");
@@ -2997,11 +3030,26 @@ export function ensurePreconditions(
         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) {

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

@@ -1,6 +1,8 @@
 // gsd-pi + src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts - Handles provider and agent-end recovery for GSD auto-mode.
 
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
+import { mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 
 import type { AgentEndEvent, ErrorContext } from "../auto/types.js";
 import { logWarning } from "../workflow-logger.js";
@@ -11,7 +13,7 @@ import {
   maybeHandleEmptyIntentTurn,
   resetEmptyTurnCounter,
 } from "../guided-flow.js";
-import { clearPathCache } from "../paths.js";
+import { clearPathCache, gsdRoot } from "../paths.js";
 import {
   getAutoDashboardData,
   getAutoModeStartModel,
@@ -33,7 +35,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, type GuidedUnitContext } from "../guided-unit-context.js";
 import { resumeAutoAfterProviderDelay } from "./provider-error-resume.js";
 import {
   classifyError,
@@ -115,9 +118,14 @@ export function isUserInitiatedAbortMessage(message: string | undefined | null):
 export function shouldDeferTransientErrorToCoreRetry(
   cls: ErrorClass,
   rawErrorMsg: string,
+  deferCheckMsg: string = rawErrorMsg,
 ): boolean {
   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);
 }
 
 type ProviderModelFallbackParams = {
@@ -154,10 +162,7 @@ async function tryProviderModelFallback(params: ProviderModelFallbackParams): Pr
           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;
         }
       }
@@ -181,10 +186,7 @@ async function tryProviderModelFallback(params: ProviderModelFallbackParams): Pr
         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;
       }
     }
@@ -393,6 +395,108 @@ export function suppressTerminalDeletedWorktreeMessageEnd(event: MessageEndLike)
   return true;
 }
 
+function modelLabel(ctx: ExtensionContext): string {
+  const provider = ctx.model?.provider;
+  const id = ctx.model?.id;
+  return provider && id ? `${provider}/${id}` : "unknown model";
+}
+
+function isFatalManualGuidedTerminalFailure(lastMsg: unknown): boolean {
+  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: unknown): string {
+  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: string): string {
+  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: string,
+  unitType: string,
+  model: string,
+  detail: string,
+  stopReason: unknown,
+): void {
+  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: ExtensionContext,
+  lastMsg: unknown,
+  guidedUnit: GuidedUnitContext | null,
+): void {
+  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: ErrorClass,
   pi: ExtensionAPI,
@@ -442,7 +546,9 @@ export async function handleAgentEnd(
   // 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)) {
@@ -471,13 +577,15 @@ export async function handleAgentEnd(
   // discussions (where isAutoActive may be false) still get recovered.
   if (maybeHandleEmptyIntentTurn(event, isAutoActive(), basePath)) return;
 
-  if (!isAutoActive()) return;
+  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;
@@ -560,9 +668,9 @@ export async function handleAgentEnd(
       });
       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,
@@ -581,8 +689,8 @@ export async function handleAgentEnd(
     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
@@ -660,11 +768,32 @@ export async function handleAgentEnd(
     // 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",
@@ -732,58 +861,22 @@ export async function handleAgentEnd(
     // --- 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;
       }
     }
 

package/src/resources/extensions/gsd/bootstrap/core-session-tools.ts

@@ -0,0 +1,44 @@
+// 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",
+] as const;
+
+/** Tools excluded from the high per-turn loop-guard cap (strict or orchestration). */
+const NON_REPEATABLE_FROM_MINIMAL_BASE = new Set<string>([
+  "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",
+] as const;
+
+/** 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,
+] as const;
+
+export const INHERENTLY_REPEATABLE_TOOL_SET = new Set<string>(INHERENTLY_REPEATABLE_TOOL_NAMES);

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

@@ -3,6 +3,7 @@
 import { Type, StringEnum } from "@gsd/pi-ai";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 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";
@@ -392,13 +393,17 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "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: any, theme: any) {
@@ -685,8 +690,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
     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({
@@ -694,7 +700,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       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" }),
@@ -704,12 +710,14 @@ export function registerDbTools(pi: ExtensionAPI): void {
         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" }),
+        targetRepositories: Type.Optional(Type.Array(Type.String(), { description: "Repository id(s) this task touches (parent workspace); must match a Declared Repository. Omit for single-repo projects." })),
+      }), { 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" })),
       integrationClosure: Type.Optional(Type.String({ description: "Slice integration closure" })),
       observabilityImpact: Type.Optional(Type.String({ description: "Slice observability impact" })),
+      targetRepositories: Type.Optional(Type.Array(Type.String(), { description: "Slice-wide default repository id(s) (parent workspace); must match a Declared Repository. Omit for single-repo projects." })),
       // 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')" })),
@@ -783,6 +791,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       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" })),
+      targetRepositories: Type.Optional(Type.Array(Type.String(), { description: "Repository id(s) this task touches (parent workspace); must match a Declared Repository. Omit for single-repo projects." })),
       // 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')" })),

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

@@ -72,6 +72,7 @@ export function registerExecTools(pi: ExtensionAPI): void {
       return executeUatExec(params as Parameters<typeof executeUatExec>[0], {
         baseDir,
         preferences: await loadContextModePreferences(baseDir),
+        signal: _signal,
       });
     },
   });
@@ -119,6 +120,7 @@ export function registerExecTools(pi: ExtensionAPI): void {
       return executeGsdExec(params as Parameters<typeof executeGsdExec>[0], {
         baseDir,
         preferences: await loadContextModePreferences(baseDir),
+        signal: _signal,
       });
     },
   });