@opengsd/gsd-pi 1.2.0-dev.b1abb545 → 1.2.0-dev.fb12b103

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

@@ -14,13 +14,14 @@ import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
 import type { AutoAdvanceResult, AutoOrchestrationModule, AutoSessionContext, AutoStatus, AutoTerminalOutcome } from "./contracts.js";
 import type { AutoSession, PendingOrchestrationDispatch } from "./session.js";
-import type { GSDState } from "../types.js";
+import type { GSDState, Phase } from "../types.js";
 import type { MinimalModelRegistry } from "../context-budget.js";
 
 type BlockedAdvanceResult = Extract<AutoAdvanceResult, { kind: "blocked" }>;
 
-import { debugCount, debugTime } from "../debug-logger.js";
+import { debugCount, debugLog, debugTime } from "../debug-logger.js";
 import { reconcileBeforeDispatch } from "../state-reconciliation.js";
+import { isLegalEdge, IllegalPhaseTransitionError } from "../state-transition-matrix.js";
 import { resolveDispatch } from "../auto-dispatch.js";
 import { classifyFailure } from "../recovery-classification.js";
 import { verifyExpectedArtifact, refreshRecoveryDbForArtifact } from "../auto-recovery.js";
@@ -37,7 +38,7 @@ import { checkResourcesStale, autoWorktreeBranch, mergeMilestoneToMain } from ".
 import { getSessionLockStatus } from "../session-lock.js";
 import { resolveUokFlags } from "../uok/flags.js";
 import { emitJournalEvent as _emitJournalEvent } from "../journal.js";
-import { loadEffectiveGSDPreferences, getIsolationMode } from "../preferences.js";
+import { loadEffectiveGSDPreferences, getIsolationMode, resolveEffectiveUnitIsolationMode } from "../preferences.js";
 import {
   detectWorktreeName,
   getMainBranch,
@@ -330,6 +331,10 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   private lastAdvanceKey: string | null = null;
   private lastFinalizedUnitKey: string | null = null;
   private dispatchKeyWindow: string[] = [];
+  // ADR-030 Phase Transition Invariant: the prior advance's reconciled Phase,
+  // the "from" endpoint of the edge check. In-memory; reset on start/resume/stop
+  // so the first advance of a session has no edge to assert.
+  private lastDerivedPhase: Phase | null = null;
   // #442: the unit key we last attempted graduated stuck-recovery for. Bounds
   // recovery to one attempt per stuck episode per run (reset on start/resume/
   // stop), mirroring the legacy Level-1-then-Level-2 escalation in phases.ts.
@@ -612,8 +617,11 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
   // ── WorktreeAdapter (folded) ─────────────────────────────────────────────
 
   private getEffectiveUnitIsolationMode(basePath: string): ReturnType<typeof getIsolationMode> {
-    const configuredMode = getIsolationMode(basePath);
-    return configuredMode === "worktree" && this.s.isolationDegraded ? "branch" : configuredMode;
+    return resolveEffectiveUnitIsolationMode(
+      getIsolationMode(basePath),
+      this.s.isolationDegraded,
+      this.s.strandedRecoveryIsolationMode,
+    );
   }
 
   private buildLifecycle(): WorktreeLifecycle {
@@ -724,6 +732,21 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     return { action: recovery.action, reason: recovery.reason };
   }
 
+  /**
+   * ADR-030 Phase Transition Invariant (advisory mode). The matrix is an
+   * assertion, not a decision-maker — deriveState already chose the phase; we
+   * only observe illegal *derived* edges that survived reconciliation. The
+   * matrix is still a sparse hardening spec, so this is telemetry-only (no
+   * block) until it is expanded into a validated legal-edge graph. To enforce:
+   * `throw violation;` instead of logging — recovery-classification maps
+   * IllegalPhaseTransitionError to kind "illegal-transition" (escalate).
+   */
+  private observePhaseTransition(from: Phase, to: Phase): void {
+    if (isLegalEdge(from, to)) return;
+    const violation = new IllegalPhaseTransitionError(from, to);
+    debugLog("phase-transition-advisory", { from, to, message: violation.message });
+  }
+
   // ── Lifecycle verbs ──────────────────────────────────────────────────────
 
   /**
@@ -787,6 +810,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     this.lastFinalizedUnitKey = null;
     this.dispatchKeyWindow = [];
     this.lastStuckRecoveryKey = null;
+    this.lastDerivedPhase = null;
     this.status.phase = "running";
     this.bumpTransition();
     this.journalTransition({ name: "start" });
@@ -876,6 +900,12 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         return blocked;
       }
 
+      const reconciledPhase = reconciliation.stateSnapshot.phase;
+      if (this.lastDerivedPhase !== null) {
+        this.observePhaseTransition(this.lastDerivedPhase, reconciledPhase);
+      }
+      this.lastDerivedPhase = reconciledPhase;
+
       const decision = await this.decideNextUnit({ stateSnapshot: reconciliation.stateSnapshot });
       if (!decision) {
         const settlementBlock = this.evaluateNoRemainingUnitsSettlement(reconciliation.stateSnapshot);
@@ -993,16 +1023,18 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
       // 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: AutoAdvanceResult = { kind: "blocked", reason: "idempotent advance: unit already active", action: "pause" };
+        const skipped: AutoAdvanceResult = { 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
@@ -1146,6 +1178,9 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     // Preserve dispatchKeyWindow across resume so stuck-loop detection
     // accumulates across pause/resume cycles rather than resetting each time.
     this.lastStuckRecoveryKey = null;
+    // ADR-030: drop the prior "from" — the first advance after resume has no
+    // edge to assert (avoids a false illegal-edge across the pause boundary).
+    this.lastDerivedPhase = null;
     this.status.phase = "running";
     this.bumpTransition();
     this.journalTransition({ name: "resume" });
@@ -1162,6 +1197,7 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
     this.status.activeUnit = undefined;
     this.lastAdvanceKey = null;
     this.lastFinalizedUnitKey = null;
+    this.lastDerivedPhase = null;
     // Preserve dispatchKeyWindow on pause so stuck-loop detection accumulates
     // across pause/resume cycles. Only clear on a hard stop.
     if (reason !== "pause") {

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

@@ -20,6 +20,7 @@ import {
   type PreVerificationOpts,
 } from "../auto-post-unit.js";
 import { lastAssistantText } from "../user-input-boundary.js";
+import { resolveEffectiveUnitIsolationMode } from "../preferences.js";
 import type { Phase } from "../types.js";
 import {
   MAX_RECOVERY_CHARS,
@@ -362,7 +363,15 @@ async function validateSourceWriteWorktreeSafety(
   if (!writesSource) return null;
 
   const projectRoot = s.canonicalProjectRoot ?? resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
-  const isolationMode = deps.getIsolationMode(projectRoot);
+  // A degraded session already fell back to the milestone branch in the
+  // project root — validating against the canonical worktree root there
+  // would fail every dispatch with a false invalid-root. The same applies
+  // to a stranded-recovery session that adopted the milestone branch.
+  const isolationMode = resolveEffectiveUnitIsolationMode(
+    deps.getIsolationMode(projectRoot),
+    s.isolationDegraded,
+    s.strandedRecoveryIsolationMode,
+  );
   if (isolationMode !== "worktree") return null;
 
   const safety = createWorktreeSafetyModule();

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

@@ -90,7 +90,9 @@ import { MILESTONE_ID_RE } from "./milestone-ids.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";
@@ -772,6 +774,16 @@ export const DISPATCH_RULES: DispatchRule[] = [
       if (browserToolError) {
         return { action: "stop" as const, reason: browserToolError, level: "warning" as const };
       }
+      const browserDaemonError = prepareBrowserDaemonForUat({
+        uatType,
+        sessionProvider,
+        sessionAuthMode,
+        sessionBaseUrl,
+        projectRoot: resolveWorkflowMcpProjectRoot(basePath),
+      });
+      if (browserDaemonError) {
+        return { action: "stop" as const, reason: browserDaemonError, level: "warning" as const };
+      }
 
       // Cap run-uat dispatch attempts to prevent infinite replay (#3624).
       // Check before incrementing so an exhausted counter cannot create a

package/src/resources/extensions/gsd/auto-model-selection.ts

@@ -1041,16 +1041,36 @@ export function resolveModelId<T extends { id: string; provider: string }>(
     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",
+] as const;
+
 /**
  * Flat-rate providers charge the same per request regardless of model.
  * Dynamic routing provides no cost benefit — it only degrades quality (#3453).

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -72,7 +72,7 @@ import {
 } from "./milestone-closeout.js";
 import type { AutoSession, SidecarItem } from "./auto/session.js";
 import { getEvidence, clearEvidenceFromDisk, isExecutionToolName } from "./safety/evidence-collector.js";
-import { validateFileChanges } from "./safety/file-change-validator.js";
+import { validateFileChanges, effectiveFileChangeAllowlist } from "./safety/file-change-validator.js";
 import { crossReferenceEvidence, type ClaimedEvidence } from "./safety/evidence-cross-ref.js";
 import { validateContent } from "./safety/content-validator.js";
 import { resolveSafetyHarnessConfig } from "./safety/safety-harness.js";
@@ -88,7 +88,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,
@@ -619,8 +619,10 @@ export function _hasExecutionToolCallsInSessionForTest(entries: readonly unknown
       return true;
     }
 
-    if (e?.type !== "message") continue;
-    const msg = e?.message;
+    // Accept both session-manager entries ({type: "message", message}) and
+    // bare agent-end messages ({role, content}) — the auto loop passes the
+    // latter via opts.agentEndMessages.
+    const msg = e?.type === "message" ? e?.message : e;
     if (!msg || msg.role !== "assistant" || !Array.isArray(msg.content)) continue;
     for (const block of msg.content) {
       if (block?.type !== "toolCall") continue;
@@ -1535,6 +1537,11 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
       if (safetyConfig.enabled) {
         const { milestone: sMid, slice: sSid, task: sTid } = parseUnitId(s.currentUnit.id);
 
+        const fileChangeAllowlist = effectiveFileChangeAllowlist(
+          safetyConfig.file_change_allowlist,
+          (prefs?.git as { manage_gitignore?: boolean } | undefined)?.manage_gitignore,
+        );
+
         // File change validation (execute-task only, after unit execution)
         if (safetyConfig.file_change_validation && s.currentUnit.type === "execute-task" && sMid && sSid && sTid) {
           try {
@@ -1554,7 +1561,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
                   files: taskRow.files,
                 })),
               );
-              const audit = validateFileChanges(s.basePath, expectedOutput, plannedFiles, safetyConfig.file_change_allowlist);
+              const audit = validateFileChanges(s.basePath, expectedOutput, plannedFiles, fileChangeAllowlist);
               if (audit && audit.violations.length > 0) {
                 const warnings = audit.violations.filter(v => v.severity === "warning");
                 for (const v of warnings) {
@@ -1576,7 +1583,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
                   s.basePath,
                   expectedOutput,
                   plannedFiles,
-                  safetyConfig.file_change_allowlist,
+                  fileChangeAllowlist,
                 );
                 if (audit && audit.violations.length > 0) {
                   const warnings = audit.violations.filter(v => v.severity === "warning");
@@ -2015,7 +2022,18 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
           "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/src/resources/extensions/gsd/auto-prompts.ts

@@ -40,6 +40,7 @@ import {
   composeContextModeInstructions,
   composeContractedUnitContext,
   composeInlinedContext,
+  composeToolSurfaceInstructions,
   composeUnitContext,
   type ArtifactResolver,
   type ComposedUnitContextBlock,
@@ -292,10 +293,12 @@ function prependContextModeToBlock(
   block: string,
   renderMode: ContextModeRenderMode = "standalone",
 ): string {
+  const toolSurface = composeToolSurfaceInstructions(unitType, { renderMode });
   const contextMode = renderContextModeBlockForPrompt(unitType, base, renderMode);
-  if (!contextMode) return block;
-  if (!block.trim()) return contextMode;
-  return `${contextMode}\n\n${block}`;
+  const guidance = [toolSurface, contextMode].filter(Boolean).join("\n\n");
+  if (!guidance) return block;
+  if (!block.trim()) return guidance;
+  return `${guidance}\n\n${block}`;
 }
 
 function requireUnitPromptContextContract(unitType: string): UnitPromptContextContract {
@@ -2470,6 +2473,9 @@ export async function buildPlanSlicePrompt(
       `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` +
@@ -3847,18 +3853,22 @@ export async function buildReactiveExecutePrompt(
   const inlinedTemplates = inlineTemplate("task-summary", "Task Summary");
   trackPromptContext(contextTelemetry, "templates", "inline", inlinedTemplates);
 
-  const prompt = loadPrompt("reactive-execute", {
-    workingDirectory: base,
-    milestoneId: mid,
-    milestoneTitle: midTitle,
-    sliceId: sid,
-    sliceTitle: sTitle,
-    graphContext: prependContextModeToBlock("reactive-execute", base, graphContext),
-    readyTaskCount: String(readyTaskIds.length),
-    readyTaskList: readyTaskListLines.join("\n"),
-    subagentPrompts: subagentSections.join("\n\n---\n\n"),
-    inlinedTemplates,
-  });
+  const prompt = prependContextModeToBlock(
+    "reactive-execute",
+    base,
+    loadPrompt("reactive-execute", {
+      workingDirectory: base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      sliceId: sid,
+      sliceTitle: sTitle,
+      graphContext,
+      readyTaskCount: String(readyTaskIds.length),
+      readyTaskList: readyTaskListLines.join("\n"),
+      subagentPrompts: subagentSections.join("\n\n---\n\n"),
+      inlinedTemplates,
+    }),
+  );
   emitPromptContextTelemetry("reactive-execute", contextTelemetry, prompt);
   return prompt;
 }
@@ -4037,17 +4047,21 @@ export async function buildGateEvaluatePrompt(
     ].join("\n"));
   }
 
-  return loadPrompt("gate-evaluate", {
-    workingDirectory: base,
-    milestoneId: mid,
-    milestoneTitle: midTitle,
-    sliceId: sid,
-    sliceTitle: sTitle,
-    slicePlanContent: prependContextModeToBlock("gate-evaluate", base, planContent),
-    gateCount: String(pending.length),
-    gateList: gateListLines.join("\n"),
-    subagentPrompts: subagentSections.join("\n\n---\n\n"),
-  });
+  return prependContextModeToBlock(
+    "gate-evaluate",
+    base,
+    loadPrompt("gate-evaluate", {
+      workingDirectory: base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      sliceId: sid,
+      sliceTitle: sTitle,
+      slicePlanContent: planContent,
+      gateCount: String(pending.length),
+      gateList: gateListLines.join("\n"),
+      subagentPrompts: subagentSections.join("\n\n---\n\n"),
+    }),
+  );
 }
 
 export async function buildRewriteDocsPrompt(

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

@@ -16,6 +16,7 @@ import type {
   ExtensionCommandContext,
 } from "@gsd/pi-coding-agent";
 import { deriveState } from "./state.js";
+import { findWorktreeSegment, isGsdWorktreePath } from "./worktree-root.js";
 import { loadFile, getManifestStatus } from "./files.js";
 import type { InterruptedSessionAssessment } from "./interrupted-session.js";
 import {
@@ -56,7 +57,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";
@@ -96,7 +98,6 @@ import {
   rmSync,
 } from "node:fs";
 import { join } from "node:path";
-import { sep as pathSep } from "node:path";
 
 import { validateDirectory } from "./validate-directory.js";
 import {
@@ -601,7 +602,7 @@ export function auditOrphanedMilestoneBranches(
               warnings.push(`Failed to remove worktree directory for ${milestoneId}: ${err2 instanceof Error ? err2.message : String(err2)}`);
             }
           } else {
-            warnings.push(`Orphaned worktree directory for ${milestoneId} is outside .gsd/worktrees/ — skipping removal for safety.`);
+            warnings.push(`Orphaned worktree directory for ${milestoneId} is outside the GSD worktrees containers — skipping removal for safety.`);
           }
         } else {
           pushAction({
@@ -717,7 +718,7 @@ export function auditOrphanedMilestoneBranches(
     if (!existsSync(wtDir)) continue;
     if (!isInsideWorktreesDir(basePath, wtDir)) {
       warnings.push(
-        `Orphaned worktree directory for ${m.id} is outside .gsd/worktrees/ — skipping removal for safety.`,
+        `Orphaned worktree directory for ${m.id} is outside the GSD worktrees containers — skipping removal for safety.`,
       );
       continue;
     }
@@ -993,12 +994,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 +1013,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 +1043,8 @@ export async function bootstrapAutoSession(
     : null;
   const startThinkingSnapshot = pi.getThinkingLevel();
   const startModelSnapshot = manualSessionOverride
-    ?? currentSessionModel
     ?? validatedPreferredModel
+    ?? currentSessionModel
     ?? null;
 
   try {
@@ -1325,7 +1328,7 @@ export async function bootstrapAutoSession(
       (state.phase === "pre-planning" || state.phase === "complete") &&
       survivorIsolationMode !== "none" &&
       !detectWorktreeName(base) &&
-      !base.includes(`${pathSep}.gsd${pathSep}worktrees${pathSep}`)
+      !isGsdWorktreePath(base)
     ) {
       const milestoneBranch = `milestone/${survivorMilestoneId}`;
       const { nativeBranchExists } = await import("./native-git-bridge.js");
@@ -1610,16 +1613,12 @@ export async function bootstrapAutoSession(
     // live here is gone.
 
     const isUnderGsdWorktrees = (p: string): boolean => {
-      // Direct layout: /.gsd/worktrees/
-      const marker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
-      if (p.includes(marker)) return true;
-      const worktreesSuffix = `${pathSep}.gsd${pathSep}worktrees`;
-      if (p.endsWith(worktreesSuffix)) return true;
-      // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
-      const symlinkRe = new RegExp(
-        `\\${pathSep}\\.gsd\\${pathSep}projects\\${pathSep}[a-f0-9]+\\${pathSep}worktrees(?:\\${pathSep}|$)`,
-      );
-      return symlinkRe.test(p);
+      const normalized = p.replaceAll("\\", "/");
+      if (findWorktreeSegment(normalized) !== null) return true;
+      // 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 (

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

@@ -15,22 +15,15 @@ export {
   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",
@@ -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-worktree-repair.ts

@@ -5,6 +5,7 @@ import { existsSync, lstatSync, readdirSync, type Stats } from "node:fs";
 import { join } from "node:path";
 
 import { worktreePath } from "./worktree-manager.js";
+import { worktreesDirs } from "./worktree-placement.js";
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
 import type { WorktreeSafetyResult } from "./worktree-safety.js";
 
@@ -39,6 +40,16 @@ export function expectedAutoWorktreePath(
   return worktreePath(projectRoot, id);
 }
 
+/** Every path the milestone worktree may legitimately live at (canonical + legacy). */
+function candidateAutoWorktreePaths(
+  projectRoot: string,
+  milestoneId: string | null | undefined,
+): string[] {
+  const id = milestoneId?.trim();
+  if (!id || !isValidMilestoneId(id)) return [];
+  return worktreesDirs(projectRoot).map((dir) => join(dir, id));
+}
+
 export function resolvePausedAutoWorktreePath(input: {
   basePath: string;
   originalBasePath?: string | null;
@@ -82,8 +93,8 @@ export function assessAutoWorktreeRepairTarget(input: {
   if (!expectedPath) {
     return { ok: false, reason: "missing expected worktree path" };
   }
-  const computedExpectedPath = expectedAutoWorktreePath(input.projectRoot, input.milestoneId);
-  if (!computedExpectedPath || !samePath(expectedPath, computedExpectedPath)) {
+  const candidatePaths = candidateAutoWorktreePaths(input.projectRoot, input.milestoneId);
+  if (candidatePaths.length === 0 || !candidatePaths.some((candidate) => samePath(expectedPath, candidate))) {
     return { ok: false, reason: "expected worktree path does not match milestone" };
   }
   if (!samePath(input.activeRoot, input.projectRoot) && !samePath(input.activeRoot, expectedPath)) {