@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.d6c5343c

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

@@ -28,6 +28,7 @@ import { ensureGsdSymlink, isInheritedRepo, validateProjectId } from "./repo-ide
 import { migrateToExternalState, recoverFailedMigration } from "./migrate-external.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import { gsdRoot, resolveMilestoneFile } from "./paths.js";
+import { milestoneEntryBlockedGuidance } from "./guidance.js";
 import { invalidateAllCaches } from "./cache.js";
 import { writeLock, clearLock, readCrashLock, isLockProcessAlive } from "./crash-recovery.js";
 import {
@@ -57,7 +58,8 @@ import {
   detectWorktreeName,
   setActiveMilestoneId,
 } from "./worktree.js";
-import { getAutoWorktreePath, isInAutoWorktree, checkoutBranchWithStashGuard } from "./auto-worktree.js";
+import { getAutoWorktreePath, isInAutoWorktree } from "./auto-worktree.js";
+import { checkoutBranchWithStashGuard } from "./worktree-git-recovery.js";
 import { readResourceVersion, cleanStaleRuntimeUnits } from "./auto-worktree.js";
 import { worktreePath as getWorktreeDir, isInsideWorktreesDir } from "./worktree-manager.js";
 import { emitWorktreeOrphaned } from "./worktree-telemetry.js";
@@ -993,12 +995,14 @@ export async function bootstrapAutoSession(
   // phase-specific planning model for a discuss turn (#2829).
   //
   // Precedence:
-  // 1) Explicit session override via /gsd model (this session)
-  // 2) Current session model from settings/session restore (if provider ready)
-  // 3) GSD model preferences from PREFERENCES.md (validated against live auth)
+  // 1) Explicit session override via /gsd model or /gsd auto --model (this session)
+  // 2) GSD model preferences from PREFERENCES.md (validated against live auth)
+  // 3) Current session model from settings/session restore (if provider ready)
   //
-  // This preserves #3517 defaults while honoring explicit runtime model
-  // selection for subsequent /gsd runs in the same session.
+  // PREFERENCES.md wins over the ambient session default (#3517) so /gsd auto
+  // does not stick on claude-code/claude-sonnet-4-6 when the user configured
+  // models via /gsd workflow-preferences or PREFERENCES.md. Custom providers
+  // still skip PREFERENCES.md entirely (#4122).
   //
   // Exception (#4122): when the session provider is a custom provider declared
   // in ~/.gsd/agent/models.json (Ollama, vLLM, OpenAI-compatible proxy, etc.),
@@ -1010,7 +1014,7 @@ export async function bootstrapAutoSession(
   const sessionProviderIsCustom = isCustomProvider(ctx.model?.provider);
   const preferredModel = sessionProviderIsCustom
     ? null
-    : resolveDefaultSessionModel(ctx.model?.provider);
+    : resolveDefaultSessionModel(ctx.model?.provider, base);
   // Validate the preferred model against the live registry + provider auth so
   // an unconfigured PREFERENCES.md entry (no API key / OAuth) can't become the
   // start-model snapshot. Without this, every subsequent unit would try to
@@ -1040,8 +1044,8 @@ export async function bootstrapAutoSession(
     : null;
   const startThinkingSnapshot = pi.getThinkingLevel();
   const startModelSnapshot = manualSessionOverride
-    ?? currentSessionModel
     ?? validatedPreferredModel
+    ?? currentSessionModel
     ?? null;
 
   try {
@@ -1612,8 +1616,10 @@ export async function bootstrapAutoSession(
     const isUnderGsdWorktrees = (p: string): boolean => {
       const normalized = p.replaceAll("\\", "/");
       if (findWorktreeSegment(normalized) !== null) return true;
-      // The container directory itself (no trailing worktree name).
-      return normalized.endsWith("/.gsd/worktrees") || normalized.endsWith("/.gsd-worktrees");
+      // The container directory itself (no trailing worktree name), in any layout.
+      return normalized.endsWith("/.gsd/worktrees")
+        || normalized.endsWith("/.gsd-worktrees")
+        || /\/\.gsd\/projects\/[^/]+\/worktrees$/.test(normalized);
     };
 
     if (
@@ -1640,14 +1646,9 @@ export async function bootstrapAutoSession(
             `Cannot enter milestone ${s.currentMilestoneId}: lease is held by another worker.`,
             "error",
           );
-        } else if (enterResult.reason === "creation-failed") {
-          ctx.ui.notify(
-            `Cannot enter milestone ${s.currentMilestoneId}: worktree/branch creation failed. Isolation is degraded.`,
-            "error",
-          );
-        } else if (enterResult.reason === "isolation-degraded") {
+        } else if (enterResult.reason === "creation-failed" || enterResult.reason === "isolation-degraded") {
           ctx.ui.notify(
-            `Cannot enter milestone ${s.currentMilestoneId}: isolation is degraded from a prior worktree failure. Close processes locking the worktree and retry, or run /gsd doctor fix.`,
+            milestoneEntryBlockedGuidance(s.currentMilestoneId, enterResult.reason),
             "error",
           );
         } else if (enterResult.reason === "invalid-milestone-id") {

package/src/resources/extensions/gsd/auto-tool-tracking.ts

@@ -5,6 +5,7 @@
  */
 
 import { stripMcpToolPrefix } from "@gsd/pi-ai";
+import { TOOL_SURFACE_NOT_READY } from "./tool-surface-readiness.js";
 
 interface InFlightTool {
   startedAt: number;
@@ -132,6 +133,15 @@ export function clearInFlightTools(): void {
 const TOOL_INVOCATION_ERROR_RE = /Validation failed for tool|Input validation error|Invalid arguments for tool|MCP error -32602|No such tool available|Expected ',' or '\}'(?: after property value)?(?: in JSON)?|Unexpected end of JSON|Unexpected token.*in JSON|does not provide an export named|Named export .* not found|Cannot find module|ERR_MODULE_NOT_FOUND|ERR_MODULE_NOT_EXPORTED|ERR_PACKAGE_PATH_NOT_EXPORTED/i;
 const DETERMINISTIC_POLICY_ERROR_RE = /(?:^|\b)(?:HARD BLOCK:|Blocked: \/gsd queue is a planning tool|Direct writes to \.gsd\/STATE\.md and \.gsd\/gsd\.db are blocked|This is a mechanical gate)/i;
 
+/**
+ * Matches the runtime's "tool not registered" error. Unlike the deterministic
+ * invocation failures above, this one is usually transient: the workflow MCP
+ * server registers its tool surface asynchronously after session start, so a
+ * Unit's first tool call can race the registration. Callers should retry
+ * (bounded) instead of breaking the loop.
+ */
+const TOOL_UNAVAILABLE_ERROR_RE = new RegExp(`No such tool available|${TOOL_SURFACE_NOT_READY}`, "i");
+
 /**
  * Returns true if the error message indicates a deterministic invocation or
  * policy failure (as opposed to a normal tool execution error).
@@ -141,6 +151,15 @@ export function isToolInvocationError(errorMsg: string): boolean {
   return TOOL_INVOCATION_ERROR_RE.test(errorMsg) || isDeterministicPolicyError(errorMsg);
 }
 
+/**
+ * Returns true if the error message indicates the called tool was not on the
+ * session's tool surface (MCP startup race — see TOOL_UNAVAILABLE_ERROR_RE).
+ */
+export function isToolUnavailableError(errorMsg: string): boolean {
+  if (!errorMsg) return false;
+  return TOOL_UNAVAILABLE_ERROR_RE.test(errorMsg);
+}
+
 /**
  * Returns true if the error message indicates the tool was skipped because
  * a queued user message interrupted the turn (#3595).  Retrying will produce

package/src/resources/extensions/gsd/auto-unit-tool-scope.ts

@@ -5,32 +5,25 @@ import {
 } from "./unit-tool-contracts.js";
 import {
   WORKFLOW_TOOL_ALIAS_PAIRS,
-  canonicalWorkflowSurfaceToolName,
   isWorkflowSurfaceAliasTool,
   stripMcpToolPrefix,
 } from "./workflow-tool-surface.js";
+import { canonicalWorkflowToolName } from "./engine-hook-contract.js";
 
 export {
   AUTO_UNIT_SCOPED_TOOLS,
   RUN_UAT_BROWSER_TOOL_NAMES,
 } from "./unit-tool-contracts.js";
 
-const EXECUTE_TASK_UNIT_TYPES = new Set([
-  "execute-task",
-  "execute-task-simple",
-  "reactive-execute",
-]);
-
-// These units own quality gates, but their completion handlers persist verdicts
-// from artifact sections. gsd_save_gate_result belongs to gate-evaluate, so keep
-// blocking it here with a calm redirect to the section-write path.
-const SECTION_CLOSE_GATE_UNIT_TYPES = new Set([
-  "execute-task",
-  "execute-task-simple",
-  "reactive-execute",
-  "complete-slice",
-  "validate-milestone",
-]);
+// Scope-class membership is declared per unit in the Unit Registry (ADR-033).
+// EXECUTE_TASK_UNIT_TYPES = scopeClass "execute-task"; the section-close gate
+// Set additionally includes scopeClass "section-close" — units whose completion
+// handlers persist gate verdicts from artifact sections (gsd_save_gate_result
+// belongs to gate-evaluate, so it is soft-blocked with a redirect below).
+import {
+  EXECUTE_TASK_UNIT_TYPES,
+  SECTION_CLOSE_GATE_UNIT_TYPES,
+} from "./unit-registry.js";
 
 const EXTRA_SCOPED_GSD_LIFECYCLE_TOOLS = [
   "gsd_skip_slice",
@@ -58,9 +51,9 @@ type AutoUnitToolScopeResult = {
   displayReason?: string;
 };
 
-export function canonicalWorkflowToolName(toolName: string): string {
-  return canonicalWorkflowSurfaceToolName(toolName);
-}
+// Normalizer seam lives in engine-hook-contract.ts; re-exported here for
+// existing scope importers.
+export { canonicalWorkflowToolName };
 
 export function isWorkflowAliasTool(toolName: string): boolean {
   return isWorkflowSurfaceAliasTool(toolName);
@@ -110,7 +103,7 @@ function isNativeWorkflowTool(toolName: string): boolean {
   return stripMcpToolPrefix(toolName) === "Workflow";
 }
 
-function readStringField(input: unknown, camel: string, snake: string): string | undefined {
+export function readStringField(input: unknown, camel: string, snake: string): string | undefined {
   if (!input || typeof input !== "object") return undefined;
   const record = input as Record<string, unknown>;
   const value = record[camel] ?? record[snake];

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

@@ -15,7 +15,7 @@
 
 import type { ExtensionContext, ExtensionAPI } from "@gsd/pi-coding-agent";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { gsdProjectionRoot, resolveSliceFile, resolveSlicePath, resolveMilestoneFile } from "./paths.js";
+import { gsdProjectionRoot, resolveSliceFile, resolveSlicePath } from "./paths.js";
 import { resolveMilestoneValidationVerdict } from "./milestone-validation-verdict.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { parseUnitId } from "./unit-id.js";
@@ -25,8 +25,6 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import type { GSDPreferences } from "./preferences-types.js";
 import { isClosedStatus } from "./status-guards.js";
 import { loadFile } from "./files.js";
-import { parseRoadmap } from "./parsers-legacy.js";
-import { isMilestoneComplete } from "./state.js";
 import {
   runVerificationGate,
   runVerificationGateForTargets,
@@ -373,29 +371,13 @@ async function runValidateMilestonePostCheck(
  * DB-backed projects are authoritative (#4094 peer review); falls back to
  * roadmap parsing only when the DB is unavailable.
  */
-async function countIncompleteSlices(basePath: string, milestoneId: string): Promise<number> {
-  if (isDbAvailable()) {
-    const slices = getMilestoneSlices(milestoneId);
-    if (slices.length === 0) {
-      // No DB rows — treat as "unknown", do not pause.
-      return 1;
-    }
-    return slices.filter((slice) => !isClosedStatus(slice.status)).length;
-  }
-
-  // Filesystem fallback: parse the roadmap markdown.
-  try {
-    const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-    if (!roadmapFile) return 1;
-    const roadmapContent = await loadFile(roadmapFile);
-    if (!roadmapContent) return 1;
-    const roadmap = parseRoadmap(roadmapContent);
-    if (roadmap.slices.length === 0) return 1;
-    return isMilestoneComplete(roadmap) ? 0 : 1;
-  } catch {
-    // Parsing failures should not cause false-positive pauses.
-    return 1;
-  }
+async function countIncompleteSlices(_basePath: string, milestoneId: string): Promise<number> {
+  // DB-authoritative (ADR-017): no markdown fallback. DB unavailable or no
+  // rows means "unknown" — do not pause.
+  if (!isDbAvailable()) return 1;
+  const slices = getMilestoneSlices(milestoneId);
+  if (slices.length === 0) return 1;
+  return slices.filter((slice) => !isClosedStatus(slice.status)).length;
 }
 
 /**

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

@@ -44,23 +44,21 @@ import {
   worktreePath,
   isInsideWorktreesDir,
 } from "./worktree-manager.js";
+import { worktreePathFor } from "./worktree-placement.js";
 import {
   detectWorktreeName,
   resolveGitHeadPath,
   nudgeGitBranchCache,
 } from "./worktree.js";
 import {
-  findWorktreeSegment,
   isGsdWorktreePath,
+  projectRootFromWorktreePath,
   normalizeWorktreePathForCompare,
   resolveWorktreeProjectRoot,
 } from "./worktree-root.js";
 import { autoResolveSafeConflictPaths } from "./git-conflict-resolve.js";
 import { MergeConflictError, readIntegrationBranch, resolveMilestoneIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
-import {
-  buildPullRequestEvidence,
-  createDraftPullRequestFromEvidence,
-} from "./pull-request-process.js";
+import { publishMilestone } from "./publication.js";
 import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import {
@@ -73,9 +71,6 @@ import {
   stashAlreadyExistsFilesFromError,
   stashRefFromError,
 } from "./worktree-git-recovery.js";
-
-// Re-export for existing callers/tests (auto-start.ts, checkout-branch-stash-guard.test.ts).
-export { checkoutBranchWithStashGuard } from "./worktree-git-recovery.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
@@ -290,19 +285,6 @@ export function _gitPathspecForWorktreePath(basePath: string, targetPath: string
   return gitPathspecForWorktreePath(basePath, targetPath);
 }
 
-function gitRemoteExists(basePath: string, remote: string): boolean {
-  try {
-    execFileSync("git", ["remote", "get-url", remote], {
-      cwd: basePath,
-      stdio: ["ignore", "pipe", "pipe"],
-      encoding: "utf-8",
-    });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function findRegularMergeChangedPaths(basePath: string, milestoneBranch: string, mainBranch: string): Set<string> {
   const changedPaths = new Set<string>();
   let mergeLog = "";
@@ -520,12 +502,8 @@ export function checkResourcesStale(
  * Returns the corrected base path.
  */
 export function escapeStaleWorktree(base: string): string {
-  const segment = findWorktreeSegment(base.replaceAll("\\", "/"));
-  if (!segment) return base;
-
-  // base is inside .gsd/worktrees/<something> — extract the project root.
-  // Normalization is 1:1 on characters, so the segment index is valid in `base`.
-  const projectRoot = base.slice(0, segment.gsdIdx);
+  const projectRoot = projectRootFromWorktreePath(base);
+  if (projectRoot === null) return base;
 
   // Guard: If the candidate project root's .gsd IS the user-level ~/.gsd,
   // the string-slice heuristic matched the wrong /.gsd/ boundary. This happens
@@ -1307,7 +1285,9 @@ export function getAutoWorktreePath(
 ): string | null {
   basePath = resolveWorktreeProjectRoot(basePath);
 
-  const p = worktreePath(basePath, milestoneId);
+  // basePath is already the resolved project root — go straight to placement
+  // instead of worktreePath(), which would re-resolve the root.
+  const p = worktreePathFor(basePath, milestoneId);
   if (!existsSync(p)) return null;
 
   // Validate this is a real git worktree, not a stray directory.
@@ -2049,8 +2029,6 @@ export function mergeMilestoneToMain(
       const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
       const gsdContentConflicts: string[] = [];
       const alreadyExists = stashAlreadyExistsFilesFromError(e);
-      const gsdAlreadyExists = alreadyExists.filter((f) => f.startsWith(".gsd/"));
-      const nonGsdAlreadyExists = alreadyExists.filter((f) => !f.startsWith(".gsd/"));
 
       // Untracked-file restore failures can leave marker conflicts in tracked
       // .gsd JSONL files without producing `U` status entries.
@@ -2114,11 +2092,12 @@ export function mergeMilestoneToMain(
       } else if (
         gsdUU.length === 0 &&
         nonGsdUU.length === 0 &&
-        gsdAlreadyExists.length > 0 &&
-        nonGsdAlreadyExists.length === 0
+        alreadyExists.length > 0
       ) {
-        // Untracked-file restore failure from stash pop where all collided
-        // paths are .gsd/ artifacts that already exist after merge.
+        // Untracked-file restore failure from stash pop where all collided paths
+        // already exist after merge (committed on target). Safe to drop the stash
+        // for the full alreadyExists set — they were untracked on source by
+        // definition of the "already exists, no checkout" failure.
         if (stashRefForDrop) {
           try {
             execFileSync("git", ["stash", "drop", stashRefForDrop], {
@@ -2137,10 +2116,6 @@ export function mergeMilestoneToMain(
         logWarning("reconcile", "Stash pop conflict on non-.gsd files after merge", {
           files: nonGsdUU.join(", "),
         });
-      } else if (nonGsdAlreadyExists.length > 0) {
-        logWarning("reconcile", "Stash pop restore collision on non-.gsd files after merge", {
-          files: nonGsdAlreadyExists.join(", "),
-        });
       } else {
         logWarning(
           "worktree",
@@ -2258,62 +2233,24 @@ export function mergeMilestoneToMain(
   };
 
   let shouldCleanup = false;
-  let pushed = false;
-  let prCreated = false;
   try {
-    // 10. Auto-push if enabled
-    if (prefs.auto_push === true && prefs.auto_pr !== true && !nothingToCommit) {
-      const remote = prefs.remote ?? "origin";
-      if (gitRemoteExists(originalBasePath_, remote)) {
-        try {
-          execFileSync("git", ["push", remote, mainBranch], {
-            cwd: originalBasePath_,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-          });
-          pushed = true;
-        } catch (err) {
-          // Push failure is non-fatal
-          logWarning("worktree", `git push failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-      }
-    }
-
-    // 9b. Auto-create PR if enabled (#2302: no longer gated on pushed/auto_push)
-    if (prefs.auto_pr === true && !nothingToCommit) {
-      const remote = prefs.remote ?? "origin";
-      const prTarget = prefs.pr_target_branch ?? mainBranch;
-      if (gitRemoteExists(originalBasePath_, remote)) {
-        try {
-          // Push the milestone branch to remote first
-          execFileSync("git", ["push", remote, milestoneBranch], {
-            cwd: originalBasePath_,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-          });
-          const prEvidence = buildPullRequestEvidence({
-            milestoneId,
-            milestoneTitle,
-            changeType: "feat",
-            summaries: completedSlices.map((slice) => `### ${slice.id}\n${slice.title}`),
-            testsRun: ["Auto-created after milestone merge. Run `npm run verify:merge` before marking this draft ready."],
-            rollbackNotes: ["Close the draft PR or revert the merge commit if review finds a behavior regression."],
-            how: "Generated by git.auto_pr after the milestone branch was pushed and merged locally.",
-          });
-          const prUrl = createDraftPullRequestFromEvidence(originalBasePath_, milestoneId, prEvidence, {
-            head: milestoneBranch,
-            base: prTarget,
-          });
-          if (!prUrl) {
-            throw new Error("gh pr create returned no URL");
-          }
-          prCreated = true;
-        } catch (err) {
-          // PR creation failure is non-fatal — gh may not be installed or authenticated
-          logWarning("worktree", `PR creation failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-      }
-    }
+    // 10/9b. Publication (auto-push / draft PR) — Publication module seam (ADR-034).
+    const publication = publishMilestone({
+      basePath: originalBasePath_,
+      milestoneId,
+      milestoneTitle,
+      integrationBranch: mainBranch,
+      milestoneBranch,
+      sliceSummaries: completedSlices.map((slice) => `### ${slice.id}\n${slice.title}`),
+      nothingToCommit,
+      prefs: {
+        autoPush: prefs.auto_push === true,
+        autoPr: prefs.auto_pr === true,
+        remote: prefs.remote,
+        prTargetBranch: prefs.pr_target_branch,
+      },
+    });
+    const { pushed, prCreated } = publication;
 
     // 11. Guard removed — step 9b (#1792) now handles this with a smarter check:
     //     throws only when the milestone has unanchored code changes, passes

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

@@ -331,6 +331,11 @@ import {
 } from "./db/auto-workers.js";
 import { releaseMilestoneLease } from "./db/milestone-leases.js";
 import { normalizeRealPath } from "./paths.js";
+import {
+  formatStopNoticePrefix,
+  isBlockedStopReason,
+  stopNoticeDisplayReason,
+} from "./stop-notice.js";
 
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
@@ -355,19 +360,7 @@ export function formatAutoStopNotification(prefix: string, totals: { cost: numbe
   ].join("\n");
 }
 
-function isBlockedStopReason(reason?: string | null): boolean {
-  return /^Blocked:\s*/i.test(reason ?? "");
-}
-
-function formatAutoStopDisplayReason(reason?: string | null): string {
-  return (reason ?? "").replace(/^Blocked:\s*/i, "").trim();
-}
-
-export function formatAutoStopNotificationPrefix(reason?: string | null): string {
-  const displayReason = formatAutoStopDisplayReason(reason);
-  const prefix = isBlockedStopReason(reason) ? "Auto-mode blocked" : "Auto-mode stopped";
-  return displayReason ? `${prefix} — ${displayReason}` : prefix;
-}
+export { formatStopNoticePrefix as formatAutoStopNotificationPrefix } from "./stop-notice.js";
 
 function clearSessionModelOverrideForCommandSession(ctx?: ExtensionContext | null): void {
   const sessionId =
@@ -1465,8 +1458,8 @@ export async function stopAuto(
 ): Promise<void> {
   if (!s.active && !s.paused) return;
   const loadedPreferences = loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences;
-  const stopNotificationPrefix = formatAutoStopNotificationPrefix(reason);
-  const displayReason = formatAutoStopDisplayReason(reason);
+  const stopNotificationPrefix = formatStopNoticePrefix(reason);
+  const displayReason = stopNoticeDisplayReason(reason);
   const isHeadlessStop = process.env.GSD_HEADLESS === "1";
   const completionStopRequested = Boolean(options.completionWidget);
   const preserveCloseoutTranscript = !isHeadlessStop && (

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

@@ -43,10 +43,8 @@ import {
 } from "../error-classifier.js";
 import { blockModel, isModelBlocked } from "../blocked-models.js";
 import { getProjectGSDPreferencesPath } from "../preferences.js";
-import {
-  formatProviderErrorGuidance,
-  resolveProviderErrorGuidance,
-} from "../provider-error-guidance.js";
+import { resolveProviderErrorGuidance } from "../provider-error-guidance.js";
+import { formatGuidance } from "../guidance.js";
 
 const retryState = createRetryState();
 const MAX_NETWORK_RETRIES = 2;
@@ -627,7 +625,7 @@ export async function handleAgentEnd(
         preferencesPath: dash.basePath ? getProjectGSDPreferencesPath(dash.basePath) : undefined,
         hasConfiguredFallbacks: (modelConfig?.fallbacks.length ?? 0) > 0,
       });
-      const guidanceText = formatProviderErrorGuidance(guidance);
+      const guidanceText = formatGuidance(guidance);
 
       await pauseForProviderModelRejection(ctx, pi, {
         errorDetail,

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

@@ -7,7 +7,6 @@ import { join } from "node:path";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
 
-import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js";
 import { logWarning } from "../workflow-logger.js";
 import { openWorkflowDatabase } from "../db-workspace.js";
 import { getAutoWorktreePath } from "../auto-worktree.js";
@@ -87,8 +86,30 @@ export function registerDynamicTools(pi: ExtensionAPI): void {
   const baseBash = createBashTool(fallbackRoot, {
     spawnHook: (ctx) => ctx,
   });
+  // The auto-mode stalled-tool watchdog only exists in GSD/auto-mode, so the
+  // watchdog verbiage is injected here (the GSD-registered tool) rather than in
+  // core bash.ts, which is reused by non-GSD embeddings that have no watchdog.
+  const WATCHDOG_DETAIL =
+    "Genuine hangs are caught by the auto-mode stalled-tool watchdog (stalled: 5m / idle: 10m / soft: 20m / hard: 30m).";
+  const gsdBashDescription = `${(baseBash as any).description} ${WATCHDOG_DETAIL}`;
+  const gsdBashParameters = (() => {
+    const params: any = (baseBash as any).parameters;
+    if (!params?.properties?.timeout) return params;
+    return {
+      ...params,
+      properties: {
+        ...params.properties,
+        timeout: {
+          ...params.properties.timeout,
+          description: `${params.properties.timeout.description} ${WATCHDOG_DETAIL}`,
+        },
+      },
+    };
+  })();
   const dynamicBash = {
     ...baseBash,
+    description: gsdBashDescription,
+    parameters: gsdBashParameters,
     execute: async (
       toolCallId: string,
       params: { command: string; timeout?: number },
@@ -100,11 +121,7 @@ export function registerDynamicTools(pi: ExtensionAPI): void {
       const fresh = createBashTool(basePath, {
         spawnHook: (spawnCtx) => ({ ...spawnCtx, cwd: basePath }),
       });
-      const paramsWithTimeout = {
-        ...params,
-        timeout: params.timeout ?? DEFAULT_BASH_TIMEOUT_SECS,
-      };
-      return (fresh as any).execute(toolCallId, paramsWithTimeout, signal, onUpdate, ctx);
+      return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
     },
   };
   pi.registerTool(dynamicBash as any);

package/src/resources/extensions/gsd/bootstrap/register-extension.ts

@@ -17,6 +17,7 @@ import { registerHooks } from "./register-hooks.js";
 import { registerShortcuts } from "./register-shortcuts.js";
 import { writeCrashLog } from "./crash-log.js";
 import { logWarning } from "../workflow-logger.js";
+import { UNIT_TOOL_CONTRACTS } from "../unit-tool-contracts.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
@@ -37,6 +38,12 @@ const EPIPE_STORM_WINDOW_MS = 10_000;
 let epipeCount = 0;
 let epipeWindowStart = 0;
 
+export const CRITICAL_GSD_WORKFLOW_TOOL_NAMES = [...new Set(
+  Object.values(UNIT_TOOL_CONTRACTS)
+    .flatMap((contract) => contract.requiredWorkflowTools)
+    .filter((toolName) => toolName.startsWith("gsd_")),
+)].sort();
+
 /** Write to stderr without ever re-throwing — stderr can EPIPE too, which would
  *  re-enter this handler and re-loop. */
 function safeStderr(msg: string): void {
@@ -133,6 +140,21 @@ export function installEpipeGuard(): void {
   }
 }
 
+function assertCriticalGsdWorkflowToolsRegistered(pi: ExtensionAPI): void {
+  if (typeof pi.getAllTools !== "function") return;
+
+  const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+  const missing = CRITICAL_GSD_WORKFLOW_TOOL_NAMES.filter((toolName) => !registered.has(toolName));
+  if (missing.length === 0) return;
+
+  const message = [
+    `Critical GSD workflow tool registration failed; missing required tool(s): ${missing.join(", ")}.`,
+    "Check earlier bootstrap warnings for the registration slot that failed.",
+  ].join(" ");
+  logWarning("bootstrap", message);
+  throw new Error(message);
+}
+
 export function registerGsdExtension(pi: ExtensionAPI): void {
   // Note: registerGSDCommand is called by index.ts before this function,
   // so we intentionally skip it here to avoid double-registration.
@@ -214,4 +236,6 @@ export function registerGsdExtension(pi: ExtensionAPI): void {
       );
     }
   }
+
+  assertCriticalGsdWorkflowToolsRegistered(pi);
 }