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

package/dist/resources/extensions/browser-tools/index.js

@@ -1,7 +1,7 @@
 /** browser-tools — Pi Browser Automation Contract adapter. */
 import { importExtensionModule } from "@gsd/pi-coding-agent";
 import { closeManagedGsdBrowser, registerManagedGsdBrowserTools, warmUpManagedGsdBrowser } from "./engine/managed-gsd-browser.js";
-import { resolveBrowserEngineMode } from "./engine/selection.js";
+import { commitBrowserEngineResolution, resolveAmbientBrowserEngineResolution } from "./engine/selection.js";
 import { setArtifactRootForCwd } from "./state.js";
 import { detectWebApp } from "./web-app-detect.js";
 let legacyRegistrationPromise = null;
@@ -130,12 +130,56 @@ function withBrowserArtifactCwdScope(pi) {
         },
     };
 }
-async function registerBrowserTools(pi) {
-    const engine = resolveBrowserEngineMode();
+/** Daemon-connect budget when the probe-resolved managed engine is verified at session start. */
+const PROBE_WARMUP_TIMEOUT_MS = 10_000;
+async function registerBrowserTools(pi, ctx) {
+    const projectRoot = ctx.cwd || process.cwd();
+    const resolution = resolveAmbientBrowserEngineResolution(projectRoot);
+    let engine = resolution.engine;
     if (engine === "off")
         return;
+    // A probe-resolved managed engine is only a prediction that gsd-browser
+    // works — prove it by connecting the daemon before committing the session's
+    // tool registrations to it. Connect failure falls back to legacy Playwright
+    // (the failure mode that made ADR-024 freeze the old default) and commits
+    // the outcome so ambient readers see the engine actually in use. When eager
+    // warm-up is disabled the daemon-connect proof cannot run, so the probe
+    // default treats the managed engine as unprovable and falls back to legacy
+    // rather than registering it unverified. An explicit
+    // GSD_BROWSER_ENGINE=gsd-browser override skips the gate and is honored
+    // verbatim, matching prior behavior.
+    if (engine === "gsd-browser" && resolution.source === "probe" && !registeredEngine) {
+        if (isWarmUpDisabled()) {
+            engine = commitLegacyFallback(projectRoot, "warm-up disabled; managed engine unverifiable; using legacy Playwright");
+        }
+        else {
+            const warmUp = await warmUpManagedGsdBrowser(ctx, AbortSignal.timeout(PROBE_WARMUP_TIMEOUT_MS));
+            if (!warmUp.ok) {
+                engine = commitLegacyFallback(projectRoot, `gsd-browser daemon connect failed (${warmUp.error}); using legacy Playwright`);
+                if (ctx.hasUI) {
+                    ctx.ui.notify(`gsd-browser engine unavailable (${warmUp.error}); using Playwright browser tools for this session.`, "warning");
+                }
+            }
+            else if (warmUp.coverageWarning && ctx.hasUI) {
+                ctx.ui.notify(warmUp.coverageWarning, "warning");
+            }
+        }
+    }
+    // Browser tool registrations are process-global and cannot be swapped once
+    // live. When an earlier session in this process already registered an engine
+    // and this project resolved a different one (per-project probe resolution can
+    // diverge across projects in a multi-session process), adopt the registered
+    // engine rather than throwing — a throw surfaces as "browser-tools failed to
+    // load" and leaves this session with no browser tools at all. Commit the
+    // adoption so ambient readers (UAT guidance, warm-up) describe the engine
+    // actually in use.
     if (registeredEngine && registeredEngine !== engine) {
-        throw new Error(`Browser tools already registered with GSD_BROWSER_ENGINE=${registeredEngine}. Restart GSD before switching to ${engine}.`);
+        engine = registeredEngine;
+        commitBrowserEngineResolution(projectRoot, {
+            engine,
+            source: "probe",
+            reason: `browser tools already registered with ${engine} earlier in this process; adopting it`,
+        });
     }
     let registration;
     if (engine === "legacy") {
@@ -165,27 +209,40 @@ async function registerBrowserTools(pi) {
         throw error;
     }
 }
+function commitLegacyFallback(projectRoot, reason) {
+    commitBrowserEngineResolution(projectRoot, { engine: "legacy", source: "probe", reason });
+    return "legacy";
+}
 function isWarmUpDisabled() {
     const value = process.env.GSD_BROWSER_WARMUP?.trim().toLowerCase();
     return value === "0" || value === "false" || value === "off";
 }
 /**
- * Auto-initialize the managed gsd-browser engine only when explicitly selected
- * for a web app. Best-effort and non-blocking: warm-up runs in the background
- * and only surfaces a warning if it fails.
+ * Auto-initialize the managed gsd-browser engine when it was selected via the
+ * explicit GSD_BROWSER_ENGINE override, which registers without the
+ * daemon-connect gate. Best-effort and non-blocking: warm-up runs in the
+ * background and only surfaces a warning if it fails. Probe-resolved sessions
+ * already connected (or fell back) during registration, so they are excluded
+ * to avoid re-warming and double-notifying.
  */
 function maybeWarmUpManagedEngine(pi, ctx) {
     if (isWarmUpDisabled())
         return;
-    if (resolveBrowserEngineMode() !== "gsd-browser")
-        return;
     const projectRoot = ctx.cwd || process.cwd();
+    const resolution = resolveAmbientBrowserEngineResolution(projectRoot);
+    if (resolution.engine !== "gsd-browser" || resolution.source !== "env")
+        return;
     if (!detectWebApp(projectRoot))
         return;
     void warmUpManagedGsdBrowser(ctx).then((result) => {
-        if (!result.ok && ctx.hasUI) {
+        if (!ctx.hasUI)
+            return;
+        if (!result.ok) {
             ctx.ui.notify(`gsd-browser auto-init failed: ${result.error}. Browser UAT tools will retry on first use; run /gsd doctor if this persists.`, "warning");
         }
+        else if (result.coverageWarning) {
+            ctx.ui.notify(result.coverageWarning, "warning");
+        }
     });
 }
 async function closeActiveBrowserEngines() {
@@ -198,14 +255,14 @@ async function closeActiveBrowserEngines() {
 export default function (pi) {
     pi.on("session_start", async (_event, ctx) => {
         if (ctx.hasUI) {
-            void registerBrowserTools(pi)
+            void registerBrowserTools(pi, ctx)
                 .then(() => maybeWarmUpManagedEngine(pi, ctx))
                 .catch((error) => {
                 ctx.ui.notify(`browser-tools failed to load: ${error instanceof Error ? error.message : String(error)}`, "warning");
             });
             return;
         }
-        await registerBrowserTools(pi);
+        await registerBrowserTools(pi, ctx);
         maybeWarmUpManagedEngine(pi, ctx);
     });
     pi.on("session_shutdown", async () => {

package/dist/resources/extensions/claude-code-cli/stream-adapter.js

@@ -24,6 +24,8 @@ import { markToolStart, markToolEnd } from "../gsd/auto.js";
 import { markInteractiveElicitationStart, markInteractiveElicitationEnd, } from "../gsd/auto-tool-tracking.js";
 import { discoverBrowserMcpServerName, discoverMcpServers, discoverMcpServerNames, discoverUserMcpServerNames, discoverWorkflowMcpServerName, computeMcpDisallowedTools, } from "../gsd/mcp-filter.js";
 import { RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES, RUN_UAT_FORBIDDEN_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES, resolveToolPresentationPlan } from "../gsd/tool-presentation-plan.js";
+import { getToolSurfaceReadinessError } from "../gsd/tool-surface-readiness.js";
+import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
 import { showInterviewRound } from "../shared/tui.js";
 export { buildFinalAssistantContent, extractToolResultsFromSdkUserMessage, handleClaudeCodePartialStreamEvent, mergePendingToolCalls, } from "./turn-assembler.js";
 export function serverToolUseToToolCallLike(block) {
@@ -1289,7 +1291,7 @@ function browserMcpServerNameFromAllowedTools(allowedTools) {
         const parsed = parseAllowedMcpToolName(toolName);
         if (!parsed)
             continue;
-        if (parsed.server === "gsd-browser" || parsed.tool.startsWith("browser_")) {
+        if (parsed.server === "gsd-browser" || hasBrowserContractPrefix(parsed.tool)) {
             return parsed.server;
         }
     }
@@ -1303,7 +1305,7 @@ function workflowMcpServerNameFromAllowedTools(allowedTools) {
         if (typeof toolName !== "string")
             continue;
         const parsed = parseAllowedMcpToolName(toolName);
-        if (!parsed || parsed.server === browserServerName || parsed.tool.startsWith("browser_"))
+        if (!parsed || parsed.server === browserServerName || hasBrowserContractPrefix(parsed.tool))
             continue;
         return parsed.server;
     }
@@ -1635,8 +1637,9 @@ async function pumpSdkMessages(model, context, options, stream) {
                 }
                 : {}),
         });
+        const workflowMcpServerName = workflowMcpServerNameFromAllowedTools(sdkOpts.allowedTools);
         const prompt = buildPromptFromContext(context, {
-            workflowMcpServerName: workflowMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
+            workflowMcpServerName,
             browserMcpServerName: browserMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
         });
         const queryPrompt = buildSdkQueryPrompt(context, prompt);
@@ -1674,7 +1677,30 @@ async function pumpSdkMessages(model, context, options, stream) {
             switch (msg.type) {
                 // -- Init --
                 case "system": {
-                    // Nothing to emit — the stream is already started.
+                    // Tool Surface Readiness gate: the init message is the first (and
+                    // only) point where the session reports its live tool surface and
+                    // MCP server statuses. If the workflow server failed or has not
+                    // registered this Unit's required tools, abort before the first
+                    // model turn with a transient, recovery-classifiable error
+                    // (tool-unavailable → retry) instead of letting the model hit
+                    // "No such tool available" mid-Unit and improvise around it.
+                    const init = msg;
+                    if (init.subtype === "init") {
+                        const readinessError = getToolSurfaceReadinessError({
+                            unitType: gsdPhase,
+                            workflowServerName: workflowMcpServerName,
+                            observation: { tools: init.tools ?? [], mcpServers: init.mcp_servers ?? [] },
+                        });
+                        if (readinessError) {
+                            controller.abort();
+                            stream.push({
+                                type: "error",
+                                reason: "error",
+                                error: makeErrorMessage(modelId, readinessError),
+                            });
+                            return;
+                        }
+                    }
                     break;
                 }
                 // -- Streaming partial messages --

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

@@ -858,16 +858,18 @@ export class AutoOrchestrator {
             // checks coexist: idempotency for the common immediate-repeat case,
             // stuck-loop for the saturated-window case.
             if (this.lastAdvanceKey === nextKey && matchingCount < STUCK_WINDOW_SIZE) {
+                // Unit already active — benign no-op. Return skipped so the loop re-polls
+                // without cancelling the in-flight unit (blocked+pause would force-cancel it).
                 this.clearPendingDispatch();
-                const blocked = { kind: "blocked", reason: "idempotent advance: unit already active", action: "pause" };
+                const skipped = { kind: "skipped", reason: "idempotent advance: unit already active" };
                 this.journalTransition({
-                    name: "advance-blocked",
-                    reason: blocked.reason,
+                    name: "advance-skipped",
+                    reason: skipped.reason,
                     unitType: decision.unitType,
                     unitId: decision.unitId,
                 });
-                this.postAdvanceRecord(blocked);
-                return blocked;
+                this.postAdvanceRecord(skipped);
+                return skipped;
             }
             // Stuck-loop detection: when the ring is saturated with copies of
             // `nextKey` (count >= STUCK_WINDOW_SIZE), the orchestrator has been

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

@@ -22,7 +22,8 @@ import { isAutoActive } from "./auto.js";
 import { markDepthVerified } from "./bootstrap/write-gate.js";
 import { ensureWorkflowPreferencesCaptured } from "./planning-depth.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
-import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForAutoUnit, } from "./workflow-mcp.js";
+import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForAutoUnit, resolveWorkflowMcpProjectRoot, } from "./workflow-mcp.js";
+import { prepareBrowserDaemonForUat } from "./browser-daemon-auto-prep.js";
 import { PROJECT_RESEARCH_INFLIGHT_MARKER, } from "./project-research-policy.js";
 import { isWorkflowPrefsCaptured, resolveDeepProjectSetupState, } from "./deep-project-setup-policy.js";
 import { annotateBackgroundable } from "./delegation-policy.js";
@@ -540,6 +541,16 @@ export const DISPATCH_RULES = [
             if (browserToolError) {
                 return { action: "stop", reason: browserToolError, level: "warning" };
             }
+            const browserDaemonError = prepareBrowserDaemonForUat({
+                uatType,
+                sessionProvider,
+                sessionAuthMode,
+                sessionBaseUrl,
+                projectRoot: resolveWorkflowMcpProjectRoot(basePath),
+            });
+            if (browserDaemonError) {
+                return { action: "stop", reason: browserDaemonError, level: "warning" };
+            }
             // Cap run-uat dispatch attempts to prevent infinite replay (#3624).
             // Check before incrementing so an exhausted counter cannot create a
             // no-progress skip loop that starves later dispatch rules.

package/dist/resources/extensions/gsd/auto-model-selection.js

@@ -839,15 +839,34 @@ export function resolveModelId(modelId, availableModels, currentProvider) {
         if (providerMatch)
             return providerMatch;
     }
-    // Prefer "anthropic" as the canonical provider for Anthropic models.
-    // Transport-specific tiebreaker (ADR-012): intentionally keys on provider,
-    // not api — we want the plain Anthropic transport when multiple are available.
-    const anthropicMatch = candidates.find(m => m.provider === "anthropic");
-    if (anthropicMatch)
-        return anthropicMatch;
+    // Subscription/OAuth routes beat pay-per-token API when the same model ID
+    // exists on multiple providers. Order matters — first match wins.
+    for (const provider of BARE_ID_SUBSCRIPTION_PROVIDER_PRECEDENCE) {
+        const match = candidates.find(m => m.provider === provider);
+        if (match)
+            return match;
+    }
     // Fall back to first non-extension candidate, or any candidate
     return candidates.find(m => !EXTENSION_PROVIDERS.has(m.provider)) ?? candidates[0];
 }
+/**
+ * When a bare model ID exists on multiple providers, prefer subscription/OAuth
+ * routes over pay-per-token API keys. Matches PROVIDER_ROUTES in doctor-providers
+ * but applies when *both* sides are authenticated.
+ *
+ * Order rationale:
+ * - openai-codex before github-copilot: ChatGPT-native for shared GPT IDs
+ * - google-gemini-cli before github-copilot: first-party Gemini CLI
+ * - anthropic before github-copilot: first-party Claude API/OAuth over Copilot
+ * - github-copilot before openai/google: Copilot OAuth over platform API keys
+ */
+export const BARE_ID_SUBSCRIPTION_PROVIDER_PRECEDENCE = [
+    "openai-codex",
+    "google-gemini-cli",
+    "anthropic",
+    "github-copilot",
+    "google-antigravity",
+];
 /**
  * Flat-rate providers charge the same per request regardless of model.
  * Dynamic routing provides no cost benefit — it only degrades quality (#3453).

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -55,7 +55,7 @@ import { writeTurnGitTransaction } from "./uok/gitops.js";
 import { isClosedStatus } from "./status-guards.js";
 import { detectAbandonMilestone } from "./abandon-detect.js";
 import { getPendingGate } from "./bootstrap/write-gate.js";
-import { isDeterministicPolicyError } from "./auto-tool-tracking.js";
+import { isDeterministicPolicyError, isToolUnavailableError } from "./auto-tool-tracking.js";
 import { formatConnectedStepStack, formatPostUnitStatusCard } from "./auto-status-message.js";
 import { clearProjectResearchInflightMarker, finalizeProjectResearchTimeout, } from "./project-research-policy.js";
 import { validateArtifact } from "./schemas/validate.js";
@@ -1701,7 +1701,16 @@ export async function postUnitPreVerification(pctx, opts) {
                 ctx.ui.notify(`Artifact missing for ${s.currentUnit.type} ${s.currentUnit.id} — DB unavailable, skipping retry.${dbSkipDiag ? ` Expected: ${dbSkipDiag}` : ""}`, "error");
             }
             else if (!triggerArtifactVerified) {
-                if (s.lastToolInvocationError) {
+                if (s.lastToolInvocationError && isToolUnavailableError(s.lastToolInvocationError)) {
+                    // Tool-unavailable is the one transient invocation error: the
+                    // workflow MCP server registers its surface asynchronously, so a
+                    // Unit's first call can race the registration. Fall through to the
+                    // bounded verification retry instead of pausing.
+                    debugLog("postUnit", { phase: "tool-unavailable-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, error: s.lastToolInvocationError });
+                    ctx.ui.notify(`Tool unavailable for ${s.currentUnit.type}: ${s.lastToolInvocationError}. The tool surface may still be registering — retrying.`, "warning");
+                    s.lastToolInvocationError = null;
+                }
+                else if (s.lastToolInvocationError) {
                     const isUserSkip = /queued user message/i.test(s.lastToolInvocationError);
                     const errMsg = isUserSkip
                         ? `Tool skipped for ${s.currentUnit.type}: ${s.lastToolInvocationError}. Queued user message interrupted the turn — pausing auto-mode.`

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

@@ -21,7 +21,7 @@ import { getPendingGatesForTurn } from "./gsd-db.js";
 import { assertGateCoverage, getGatesForTurn, } from "./gate-registry.js";
 import { formatDecisionsCompact, formatRequirementsCompact } from "./structured-data-formatter.js";
 import { readPhaseAnchor, formatAnchorForPrompt } from "./phase-anchor.js";
-import { composeContextModeInstructions, composeContractedUnitContext, composeInlinedContext, composeUnitContext, } from "./unit-context-composer.js";
+import { composeContextModeInstructions, composeContractedUnitContext, composeInlinedContext, composeToolSurfaceInstructions, composeUnitContext, } from "./unit-context-composer.js";
 import { resolveManifest } from "./unit-context-manifest.js";
 import { compileUnitContextContract } from "./tool-contract.js";
 import { readCompactionSnapshot } from "./compaction-snapshot.js";
@@ -224,12 +224,14 @@ function renderContextModeBlockForPrompt(unitType, base, renderMode = "standalon
     return `${contextMode}\n\n## Context Snapshot\nSource: \`.gsd/last-snapshot.md\`\n\n${snapshot.trimEnd()}`;
 }
 function prependContextModeToBlock(unitType, base, block, renderMode = "standalone") {
+    const toolSurface = composeToolSurfaceInstructions(unitType, { renderMode });
     const contextMode = renderContextModeBlockForPrompt(unitType, base, renderMode);
-    if (!contextMode)
+    const guidance = [toolSurface, contextMode].filter(Boolean).join("\n\n");
+    if (!guidance)
         return block;
     if (!block.trim())
-        return contextMode;
-    return `${contextMode}\n\n${block}`;
+        return guidance;
+    return `${guidance}\n\n${block}`;
 }
 function requireUnitPromptContextContract(unitType) {
     const result = compileUnitContextContract(unitType);
@@ -2146,6 +2148,9 @@ export async function buildPlanSlicePrompt(mid, _midTitle, sid, sTitle, base, le
             `Either (a) add an earlier task that creates X on disk before the task that needs it, ` +
             `or (b) if this task IS the one that creates X, move X from inputs to expected_output. ` +
             `Do NOT put X in a task's expected_output if that task only reads or verifies X — only tasks that actually write X to disk should list it in expected_output.\n` +
+            `- **"[file] X: ... GSD planning artifacts are projections preloaded as context / written by workflow tools"**: ` +
+            `Remove X from the task's inputs, files, and expectedOutput entirely. Planning artifacts (anything under .gsd/, .planning/, or .audits/, or names like M001-CONTEXT.md / S01-PLAN.md) are preloaded as context and written by workflow tools — ` +
+            `do NOT add a task that creates X and do NOT move X to expectedOutput.\n` +
             `- **"[file] X: Task T_early reads X but it's created by task T_late (sequence violation)"**: ` +
             `Either (a) reorder tasks so T_late (the creator) runs before T_early (the reader), ` +
             `or (b) if T_late doesn't actually create X (it only reads/tests it), remove X from T_late's expected_output entirely.\n` +
@@ -3338,18 +3343,18 @@ opts) {
     }
     const inlinedTemplates = inlineTemplate("task-summary", "Task Summary");
     trackPromptContext(contextTelemetry, "templates", "inline", inlinedTemplates);
-    const prompt = loadPrompt("reactive-execute", {
+    const prompt = prependContextModeToBlock("reactive-execute", base, loadPrompt("reactive-execute", {
         workingDirectory: base,
         milestoneId: mid,
         milestoneTitle: midTitle,
         sliceId: sid,
         sliceTitle: sTitle,
-        graphContext: prependContextModeToBlock("reactive-execute", base, graphContext),
+        graphContext,
         readyTaskCount: String(readyTaskIds.length),
         readyTaskList: readyTaskListLines.join("\n"),
         subagentPrompts: subagentSections.join("\n\n---\n\n"),
         inlinedTemplates,
-    });
+    }));
     emitPromptContextTelemetry("reactive-execute", contextTelemetry, prompt);
     return prompt;
 }
@@ -3489,17 +3494,17 @@ export async function buildGateEvaluatePrompt(mid, midTitle, sid, sTitle, base,
             "```",
         ].join("\n"));
     }
-    return loadPrompt("gate-evaluate", {
+    return prependContextModeToBlock("gate-evaluate", base, loadPrompt("gate-evaluate", {
         workingDirectory: base,
         milestoneId: mid,
         milestoneTitle: midTitle,
         sliceId: sid,
         sliceTitle: sTitle,
-        slicePlanContent: prependContextModeToBlock("gate-evaluate", base, planContent),
+        slicePlanContent: planContent,
         gateCount: String(pending.length),
         gateList: gateListLines.join("\n"),
         subagentPrompts: subagentSections.join("\n\n---\n\n"),
-    });
+    }));
 }
 export async function buildRewriteDocsPrompt(mid, midTitle, activeSlice, base, overrides) {
     const sid = activeSlice?.id;

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

@@ -25,7 +25,8 @@ import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
 import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit, nativeGetCurrentBranch, nativeDetectMainBranch, nativeBranchList, nativeBranchExists, nativeBranchListMerged, nativeBranchDelete, nativeWorktreeRemove, nativeCommitCountBetween, nativeHasChanges, } from "./native-git-bridge.js";
 import { GitServiceImpl } from "./git-service.js";
 import { captureIntegrationBranch, detectWorktreeName, setActiveMilestoneId, } from "./worktree.js";
-import { getAutoWorktreePath, checkoutBranchWithStashGuard } from "./auto-worktree.js";
+import { getAutoWorktreePath } 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";
@@ -740,12 +741,14 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
     // 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.),
@@ -757,7 +760,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
     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
@@ -780,8 +783,8 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         : null;
     const startThinkingSnapshot = pi.getThinkingLevel();
     const startModelSnapshot = manualSessionOverride
-        ?? currentSessionModel
         ?? validatedPreferredModel
+        ?? currentSessionModel
         ?? null;
     try {
         // Validate GSD_PROJECT_ID early so the user gets immediate feedback
@@ -1249,8 +1252,10 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             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 (s.currentMilestoneId &&
             (getIsolationMode(base) !== "none" || strandedRecoveryAction?.recoveryMode) &&

package/dist/resources/extensions/gsd/auto-tool-tracking.js

@@ -4,6 +4,7 @@
  * can distinguish "waiting for tool completion" from "truly idle".
  */
 import { stripMcpToolPrefix } from "@gsd/pi-ai";
+import { TOOL_SURFACE_NOT_READY } from "./tool-surface-readiness.js";
 const inFlightTools = new Map();
 /**
  * Tools that block waiting for human input by design.
@@ -117,6 +118,14 @@ export function clearInFlightTools() {
  */
 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).
@@ -126,6 +135,15 @@ export function isToolInvocationError(errorMsg) {
         return false;
     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) {
+    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/dist/resources/extensions/gsd/auto-unit-tool-scope.js

@@ -2,21 +2,12 @@ import { parseUnitId } from "./unit-id.js";
 import { AUTO_UNIT_SCOPED_TOOLS, getForbiddenGsdToolReason, } from "./unit-tool-contracts.js";
 import { WORKFLOW_TOOL_ALIAS_PAIRS, canonicalWorkflowSurfaceToolName, isWorkflowSurfaceAliasTool, stripMcpToolPrefix, } from "./workflow-tool-surface.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",
     "gsd_slice_reopen",
@@ -74,7 +65,7 @@ function allowedGsdToolsForUnit(unitType) {
 function isNativeWorkflowTool(toolName) {
     return stripMcpToolPrefix(toolName) === "Workflow";
 }
-function readStringField(input, camel, snake) {
+export function readStringField(input, camel, snake) {
     if (!input || typeof input !== "object")
         return undefined;
     const record = input;