gsd-pi 2.77.0 → 2.78.0-dev.aeeb2ca00

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

@@ -34,6 +34,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
 import { join } from "node:path";
 import { hasImplementationArtifacts } from "./auto-recovery.js";
+import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import {
   buildDiscussMilestonePrompt,
   buildResearchMilestonePrompt,
@@ -58,6 +59,10 @@ import {
 import { resolveModelWithFallbacksForUnit } from "./preferences-models.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { selectReactiveDispatchBatch } from "./uok/execution-graph.js";
+import { getMilestonePipelineVariant } from "./milestone-scope-classifier.js";
+import { EXECUTION_ENTRY_PHASES, hasFinalizedMilestoneContext } from "./uok/plan-v2.js";
+import { isAutoActive } from "./auto.js";
+import { markDepthVerified } from "./bootstrap/write-gate.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -88,6 +93,18 @@ export interface DispatchContext {
   modelRegistry?: MinimalModelRegistry;
 }
 
+type ReassessmentChecker = typeof checkNeedsReassessment;
+
+let reassessmentChecker: ReassessmentChecker = checkNeedsReassessment;
+
+export function setReassessmentCheckerForTest(checker: ReassessmentChecker): () => void {
+  const previous = reassessmentChecker;
+  reassessmentChecker = checker;
+  return () => {
+    reassessmentChecker = previous;
+  };
+}
+
 export interface DispatchRule {
   /** Human-readable name for debugging and test identification */
   name: string;
@@ -95,6 +112,38 @@ export interface DispatchRule {
   match: (ctx: DispatchContext) => Promise<DispatchAction | null>;
 }
 
+async function readUatGateVerdict(
+  basePath: string,
+  mid: string,
+  sliceId: string,
+): Promise<{ verdict: string; uatType: UatType | undefined } | null> {
+  const uatFile = resolveSliceFile(basePath, mid, sliceId, "UAT");
+  const assessmentFile = resolveSliceFile(basePath, mid, sliceId, "ASSESSMENT");
+
+  const uatContent = uatFile ? await loadFile(uatFile) : null;
+  const uatType = uatContent ? extractUatType(uatContent) : undefined;
+
+  const assessmentContent = assessmentFile ? await loadFile(assessmentFile) : null;
+  if (assessmentContent) {
+    const assessmentVerdict = extractVerdict(assessmentContent);
+    if (assessmentVerdict) {
+      return {
+        verdict: assessmentVerdict,
+        uatType: uatType ?? extractUatType(assessmentContent),
+      };
+    }
+  }
+
+  if (uatContent) {
+    const legacyUatVerdict = extractVerdict(uatContent);
+    if (legacyUatVerdict) {
+      return { verdict: legacyUatVerdict, uatType };
+    }
+  }
+
+  return null;
+}
+
 function missingSliceStop(mid: string, phase: string): DispatchAction {
   return {
     action: "stop",
@@ -242,6 +291,48 @@ export const DISPATCH_RULES: DispatchRule[] = [
       };
     },
   },
+  {
+    // #4671 — Recovery path for execution-entry phases with missing CONTEXT.md.
+    //
+    // Once `deriveStateFromDb` returns an execution-entry phase (executing /
+    // summarizing / validating-milestone / completing-milestone), the
+    // pre-planning guard at `pre-planning (no context) → discuss-milestone`
+    // no longer fires. The plan-v2 gate correctly detects the missing context
+    // but can only block — it cannot redispatch. Without this rule the
+    // milestone is stuck until `/gsd doctor heal` repairs it (and heal
+    // historically missed this check too).
+    //
+    // Fire BEFORE the execution-entry phase rules so we redispatch to
+    // `discuss-milestone` instead of hitting the plan-v2 gate.
+    name: "execution-entry phase (no context) → discuss-milestone",
+    match: async ({ state, mid, midTitle, basePath, structuredQuestionsAvailable }) => {
+      if (!EXECUTION_ENTRY_PHASES.has(state.phase)) return null;
+      // Align with the plan-v2 gate's lookup semantics: whitespace-only counts
+      // as missing, and an auto worktree may fall back to GSD_PROJECT_ROOT.
+      if (hasFinalizedMilestoneContext(basePath, mid)) return null;
+      // H6 fix (#4973): In auto-mode there is no human to answer the
+      // depth-verification ask_user_questions, so the write-gate deadlocks.
+      // Pre-mark the milestone as depth-verified so gsd_summary_save({artifact_type:"CONTEXT"})
+      // is not blocked. Safe ordering: session_switch fires clearDiscussionFlowState()
+      // (register-hooks.ts:106) before before_agent_start, which fires before resolveDispatch
+      // reaches this match fn — so this call always happens after any session-switch reset.
+      // Interactive sessions (isAutoActive()===false) are unaffected.
+      if (isAutoActive()) {
+        markDepthVerified(mid, basePath);
+      }
+      return {
+        action: "dispatch",
+        unitType: "discuss-milestone",
+        unitId: mid,
+        prompt: await buildDiscussMilestonePrompt(
+          mid,
+          midTitle,
+          basePath,
+          structuredQuestionsAvailable,
+        ),
+      };
+    },
+  },
   {
     name: "summarizing → complete-slice",
     match: async ({ state, mid, midTitle, basePath }) => {
@@ -302,27 +393,28 @@ export const DISPATCH_RULES: DispatchRule[] = [
       // Only applies when UAT dispatch is enabled
       if (!prefs?.uat_dispatch) return null;
 
-      const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
-
-      // DB-first: get completed slices from DB
-      let completedSliceIds: string[];
+      // DB-first: prefer closed slices from DB; fall back to ROADMAP on disk.
+      let closedSliceIds: string[];
       if (isDbAvailable()) {
-        completedSliceIds = getMilestoneSlices(mid)
-          .filter(s => s.status === "complete")
+        closedSliceIds = getMilestoneSlices(mid)
+          .filter(s => isClosedStatus(s.status))
           .map(s => s.id);
       } else {
-        return null;
+        // Filesystem fallback for degraded / unmigrated projects.
+        // `slice.done` in the parsed ROADMAP is the disk-level closed signal.
+        const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+        const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;
+        if (!roadmapContent) return null;
+        const roadmap = parseRoadmap(roadmapContent);
+        closedSliceIds = roadmap.slices.filter(s => s.done).map(s => s.id);
       }
 
-      for (const sliceId of completedSliceIds) {
-        const resultFile = resolveSliceFile(basePath, mid, sliceId, "UAT");
-        if (!resultFile) continue;
-        const content = await loadFile(resultFile);
-        if (!content) continue;
-        const verdict = extractVerdict(content);
-        const uatType = extractUatType(content);
+      for (const sliceId of closedSliceIds) {
+        const result = await readUatGateVerdict(basePath, mid, sliceId);
+        if (!result) continue;
+        const { verdict, uatType } = result;
 
-        if (verdict && !isAcceptableUatVerdict(verdict, uatType)) {
+        if (!isAcceptableUatVerdict(verdict, uatType)) {
           return {
             action: "stop" as const,
             reason: `UAT verdict for ${sliceId} is "${verdict}" — blocking progression until resolved.\nReview the UAT result and update the verdict to PASS, or re-run /gsd auto after fixing.`,
@@ -337,11 +429,15 @@ export const DISPATCH_RULES: DispatchRule[] = [
     name: "reassess-roadmap (post-completion)",
     match: async ({ state, mid, midTitle, basePath, prefs }) => {
       if (prefs?.phases?.skip_reassess) return null;
-      // Default reassess_after_slice to true — reassessment after slice completion
-      // is essential for roadmap integrity. Opt-out via explicit `false`.
-      const reassessEnabled = prefs?.phases?.reassess_after_slice ?? true;
+      // Default reassess_after_slice to false per ADR-003 §4 — most reassess
+      // units conclude "roadmap is fine" and burn a session for no change.
+      // The plan-slice prompt now carries a reassessment preamble so the
+      // next slice's planner does JIT roadmap verification at zero extra
+      // cost. Opt-in via explicit `reassess_after_slice: true` (e.g.
+      // burn-max profile) when you want the dedicated reassess session.
+      const reassessEnabled = prefs?.phases?.reassess_after_slice ?? false;
       if (!reassessEnabled) return null;
-      const needsReassess = await checkNeedsReassessment(basePath, mid, state);
+      const needsReassess = await reassessmentChecker(basePath, mid, state);
       if (!needsReassess) return null;
       return {
         action: "dispatch",
@@ -360,6 +456,12 @@ export const DISPATCH_RULES: DispatchRule[] = [
     name: "needs-discussion → discuss-milestone",
     match: async ({ state, mid, midTitle, basePath, structuredQuestionsAvailable }) => {
       if (state.phase !== "needs-discussion") return null;
+      // H6 fix (#4973): auto-mark depth-verified so the write-gate does not
+      // deadlock in non-interactive (auto-mode) runs. See ordering note at
+      // "execution-entry phase (no context) → discuss-milestone" above.
+      if (isAutoActive()) {
+        markDepthVerified(mid, basePath);
+      }
       return {
         action: "dispatch",
         unitType: "discuss-milestone",
@@ -380,6 +482,12 @@ export const DISPATCH_RULES: DispatchRule[] = [
       const contextFile = resolveMilestoneFile(basePath, mid, "CONTEXT");
       const hasContext = !!(contextFile && (await loadFile(contextFile)));
       if (hasContext) return null; // fall through to next rule
+      // H6 fix (#4973): auto-mark depth-verified so the write-gate does not
+      // deadlock in non-interactive (auto-mode) runs. See ordering note at
+      // "execution-entry phase (no context) → discuss-milestone" above.
+      if (isAutoActive()) {
+        markDepthVerified(mid, basePath);
+      }
       return {
         action: "dispatch",
         unitType: "discuss-milestone",
@@ -421,6 +529,26 @@ export const DISPATCH_RULES: DispatchRule[] = [
       };
     },
   },
+  {
+    name: "planning (require_slice_discussion) → pause for discussion (#3454)",
+    match: async ({ state, mid, basePath, prefs }) => {
+      if (state.phase !== "planning") return null;
+      if (!prefs?.phases?.require_slice_discussion) return null;
+      if (!state.activeSlice) return null;
+      // Only pause if the slice has no context file yet (discussion not done).
+      // resolveSliceFile returns null when the file does not exist on disk,
+      // but cachedReaddir could return a stale hit — verify with existsSync
+      // so the guard is defence-in-depth and the contract is explicit at the
+      // call site.
+      const sliceContextFile = resolveSliceFile(basePath, mid, state.activeSlice.id, "CONTEXT");
+      if (sliceContextFile && existsSync(sliceContextFile)) return null; // discussion already done, proceed
+      return {
+        action: "stop" as const,
+        reason: `Slice ${state.activeSlice.id} requires discussion before planning (require_slice_discussion is enabled). Run /gsd discuss to discuss this slice, then /gsd auto to resume.`,
+        level: "info" as const,
+      };
+    },
+  },
   {
     // Keep this rule before the single-slice research rule so the multi-slice
     // path wins whenever 2+ slices are ready.
@@ -428,6 +556,11 @@ export const DISPATCH_RULES: DispatchRule[] = [
     match: async ({ state, mid, midTitle, basePath, prefs }) => {
       if (state.phase !== "planning") return null;
       if (prefs?.phases?.skip_research || prefs?.phases?.skip_slice_research) return null;
+      // #4781 phase 2: trivial-scope milestones skip dedicated slice research.
+      // plan-slice absorbs the lightweight discovery a trivial deliverable
+      // needs. Null result (DB unavailable / unknown) falls through to today's
+      // behavior.
+      if (await getMilestonePipelineVariant(mid) === "trivial") return null;
 
       // Load roadmap to find all slices
       const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
@@ -484,6 +617,8 @@ export const DISPATCH_RULES: DispatchRule[] = [
       // Phase skip: skip research when preference or profile says so
       if (prefs?.phases?.skip_research || prefs?.phases?.skip_slice_research)
         return null;
+      // #4781 phase 2: trivial-scope milestones skip dedicated slice research.
+      if (await getMilestonePipelineVariant(mid) === "trivial") return null;
       if (!state.activeSlice) return missingSliceStop(mid, state.phase);
       const sid = state.activeSlice!.id;
       const sTitle = state.activeSlice!.title;
@@ -836,8 +971,13 @@ export const DISPATCH_RULES: DispatchRule[] = [
         };
       }
 
-      // Skip preference: write a minimal pass-through VALIDATION file
-      if (prefs?.phases?.skip_milestone_validation) {
+      // #4781 phase 2: trivial-scope milestones skip the dedicated validate
+      // unit — complete-milestone's own verification steps (3/4/5 in the
+      // closer prompt) are sufficient proof for contained deliverables.
+      const trivialVariant = await getMilestonePipelineVariant(mid) === "trivial";
+
+      // Skip preference OR trivial scope: write a minimal pass-through VALIDATION file.
+      if (prefs?.phases?.skip_milestone_validation || trivialVariant) {
         const mDir = resolveMilestonePath(basePath, mid);
         if (mDir) {
           if (!existsSync(mDir)) mkdirSync(mDir, { recursive: true });
@@ -845,15 +985,18 @@ export const DISPATCH_RULES: DispatchRule[] = [
             mDir,
             buildMilestoneFileName(mid, "VALIDATION"),
           );
+          const skipSource = trivialVariant
+            ? "trivial-scope pipeline variant (#4781)"
+            : "`skip_milestone_validation` preference";
           const content = [
             "---",
             "verdict: pass",
             "remediation_round: 0",
             "---",
             "",
-            "# Milestone Validation (skipped by preference)",
+            "# Milestone Validation (skipped)",
             "",
-            "Milestone validation was skipped via `skip_milestone_validation` preference.",
+            `Milestone validation was skipped via ${skipSource}.`,
           ].join("\n");
           writeFileSync(validationPath, content, "utf-8");
         }
@@ -883,21 +1026,13 @@ export const DISPATCH_RULES: DispatchRule[] = [
         }
       }
 
-      // Reconciliation guard (#4324): when the SUMMARY file already exists
-      // on disk but the DB says the milestone is not complete, the DB is
-      // out of sync (e.g. journal reset, partial merge, crash recovery).
-      // Reconcile the DB status directly instead of re-dispatching the
-      // tool, which would overwrite the richer on-disk SUMMARY with a
-      // thinner regenerated version — causing silent data loss.
       const existingSummary = resolveMilestoneFile(basePath, mid, "SUMMARY");
-      if (existingSummary && isDbAvailable()) {
-        try {
-          updateMilestoneStatus(mid, "complete", new Date().toISOString());
-          logWarning("dispatch", `Milestone ${mid} has SUMMARY on disk but DB status was not complete — reconciled DB to complete (#4324)`);
-        } catch (err) {
-          logWarning("dispatch", `Failed to reconcile milestone ${mid} status: ${err instanceof Error ? err.message : String(err)}`);
+      let summaryOutcome: "success" | "failure" | "unknown" = "unknown";
+      if (existingSummary) {
+        const summaryContent = await loadFile(existingSummary);
+        if (summaryContent) {
+          summaryOutcome = classifyMilestoneSummaryContent(summaryContent);
         }
-        return { action: "skip" };
       }
 
       // Safety guard (#2675): block completion when VALIDATION verdict is
@@ -932,7 +1067,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
       // Safety guard (#1703): verify the milestone produced implementation
       // artifacts (non-.gsd/ files). A milestone with only plan files and
       // zero implementation code should not be marked complete.
-      const artifactCheck = hasImplementationArtifacts(basePath);
+      const artifactCheck = hasImplementationArtifacts(basePath, mid);
       if (artifactCheck === "absent") {
         return {
           action: "stop",
@@ -982,6 +1117,48 @@ export const DISPATCH_RULES: DispatchRule[] = [
         logWarning("dispatch", `verification class check failed: ${err instanceof Error ? err.message : String(err)}`);
       }
 
+      // Disk/DB mismatch handling (#4658): SUMMARY presence alone is not enough.
+      // Apply post-gate policy:
+      // - success summary: reconcile DB and skip re-dispatch
+      // - failure summary: pause/fail-closed
+      // - unknown summary: pause/fail-closed
+      if (existingSummary) {
+        const milestone = isDbAvailable() ? getMilestone(mid) : null;
+        const status = milestone?.status ?? (isDbAvailable() ? "missing" : "unavailable");
+
+        if (summaryOutcome === "success") {
+          if (!isDbAvailable()) {
+            logWarning("dispatch", `Milestone ${mid} SUMMARY indicates completion while DB is unavailable — skipping duplicate complete-milestone dispatch`);
+            return { action: "skip" };
+          }
+          try {
+            updateMilestoneStatus(mid, "complete", new Date().toISOString());
+            logWarning("dispatch", `Milestone ${mid} SUMMARY indicates completion while DB status was "${status}" — reconciled DB to complete (#4658)`);
+            return { action: "skip" };
+          } catch (err) {
+            return {
+              action: "stop",
+              level: "warning",
+              reason: `Milestone ${mid} SUMMARY indicates completion but DB reconciliation failed (${err instanceof Error ? err.message : String(err)}). Auto-mode paused for manual review.`,
+            };
+          }
+        }
+
+        if (summaryOutcome === "failure") {
+          return {
+            action: "stop",
+            level: "warning",
+            reason: `Milestone ${mid} has a failure-path SUMMARY while DB status is "${status}". Auto-mode will not promote completion from failure artifacts. Re-run complete-milestone only after blockers are resolved and verification passes.`,
+          };
+        }
+
+        return {
+          action: "stop",
+          level: "warning",
+          reason: `Milestone ${mid} has an ambiguous SUMMARY while DB status is "${status}". Auto-mode paused instead of promoting completion from file presence alone.`,
+        };
+      }
+
       return {
         action: "dispatch",
         unitType: "complete-milestone",

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

@@ -9,7 +9,7 @@
 
 export { autoLoop, runUokKernelLoop, runLegacyAutoLoop } from "./auto/loop.js";
 export { isInfrastructureError, INFRA_ERROR_CODES } from "./auto/infra-errors.js";
-export { resolveAgentEnd, resolveAgentEndCancelled, isSessionSwitchInFlight, _resetPendingResolve, _setActiveSession } from "./auto/resolve.js";
+export { resolveAgentEnd, resolveAgentEndCancelled, isSessionSwitchInFlight, _hasPendingResolveForTest, _resetPendingResolve, _setActiveSession } from "./auto/resolve.js";
 export { detectStuck } from "./auto/detect-stuck.js";
 export { runUnit } from "./auto/run-unit.js";
 export type { LoopDeps } from "./auto/loop-deps.js";

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

@@ -19,6 +19,38 @@ import { logWarning } from "./workflow-logger.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { applyModelPolicyFilter } from "./uok/model-policy.js";
 import { isModelBlocked } from "./blocked-models.js";
+import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
+
+/**
+ * Thrown when the model-policy gate rejects every candidate model for a unit
+ * dispatch (#4959 / #4681 / #4850).  The auto-loop catches this specifically
+ * to classify the unit as `blocked` rather than counting it as a retryable
+ * iteration error — pre-send policy denial is a configuration problem, not a
+ * transient runtime failure, so retrying just burns the consecutive-error
+ * budget toward a hard stop.
+ */
+export class ModelPolicyDispatchBlockedError extends Error {
+  readonly unitType: string;
+  readonly unitId: string;
+  readonly reasons: ReadonlyArray<{ provider: string; modelId: string; reason: string }>;
+  constructor(
+    unitType: string,
+    unitId: string,
+    reasons: ReadonlyArray<{ provider: string; modelId: string; reason: string }>,
+  ) {
+    const summary = reasons.length === 0
+      ? "no candidate models"
+      : reasons
+          .slice(0, 4)
+          .map((r) => `${r.provider}/${r.modelId} (${r.reason})`)
+          .join("; ");
+    super(`Model policy denied dispatch for ${unitType}/${unitId} before prompt send. Rejected: ${summary}`);
+    this.name = "ModelPolicyDispatchBlockedError";
+    this.unitType = unitType;
+    this.unitId = unitId;
+    this.reasons = reasons;
+  }
+}
 
 export interface ModelSelectionResult {
   /** Routing metadata for metrics recording */
@@ -33,6 +65,51 @@ export interface PreferredModelConfig {
   source: "explicit" | "synthesized";
 }
 
+// Baseline active-tool set per-`pi` instance, captured the first time
+// `selectAndApplyModel` runs against that instance during an auto session
+// and re-applied before each subsequent dispatch.  WeakMap so that test
+// fakes / disposed sessions are garbage-collected normally.  See
+// #4959 / #4681 cross-unit poisoning notes at the call site below.
+//
+// LIFECYCLE: the baseline is tied to a single auto session, NOT to the
+// lifetime of the `pi` instance (which can outlive many auto runs and have
+// the user mutate tools between them).  `clearToolBaseline` MUST be called
+// at auto start AND auto stop so that a second `/gsd auto` run on the same
+// `pi` does not silently restore a stale snapshot from the prior run and
+// undo any tool changes the user made between sessions.
+const TOOL_BASELINE = new WeakMap<object, string[]>();
+
+/**
+ * Drop the captured tool baseline for `pi` so the next `selectAndApplyModel`
+ * call re-captures from the live active set.  Wired into `startAuto` and
+ * `stopAuto` in `auto.ts` to bound the baseline to a single auto session.
+ *
+ * Safe to call when no baseline is recorded (no-op).
+ */
+export function clearToolBaseline(pi: ExtensionAPI | object): void {
+  TOOL_BASELINE.delete(pi as unknown as object);
+}
+
+function restoreToolBaseline(pi: ExtensionAPI): void {
+  const key = pi as unknown as object;
+  const baseline = TOOL_BASELINE.get(key);
+  if (baseline === undefined) {
+    // First call: capture the canonical pre-dispatch tool set.  At auto-mode
+    // start the active set has not yet been narrowed for any provider.
+    // Guarded against test fakes that omit getActiveTools — record an empty
+    // baseline so subsequent calls don't keep re-probing.
+    const initial = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [];
+    TOOL_BASELINE.set(key, [...initial]);
+    return;
+  }
+  // Restore baseline before the next unit reads getActiveTools / applies
+  // post-selection adjustToolSet.  Older fakes that omit setActiveTools are
+  // tolerated — the test asserts call order on real fakes.
+  if (typeof pi.setActiveTools === "function") {
+    pi.setActiveTools([...baseline]);
+  }
+}
+
 function reapplyThinkingLevel(
   pi: ExtensionAPI,
   level: ReturnType<ExtensionAPI["getThinkingLevel"]> | null | undefined,
@@ -129,6 +206,29 @@ export async function selectAndApplyModel(
   let routing: { tier: string; modelDowngraded: boolean } | null = null;
   let appliedModel: Model<Api> | null = null;
 
+  // ── Restore active-tool baseline before policy evaluation (#4959, #4681, #4850) ──
+  // Per-unit narrowing at the bottom of this function (line ~417) calls
+  // `pi.setActiveTools(finalToolNames)` and monotonically narrows the active
+  // set across units.  Without restoration, a previously-dispatched unit on a
+  // narrow-API provider (e.g. openai-completions) leaves the active set
+  // missing tools that the next unit's selected model fully supports, but
+  // `pi.getActiveTools()` snapshot-as-hard-gate (the old behaviour) blocked
+  // dispatch with "tool policy denied" anyway.
+  //
+  // The baseline is captured once per `pi` instance via a WeakMap and
+  // re-applied here so each unit starts from a clean slate.  Soft adaptation
+  // (adjustToolSet at the bottom of this function) still trims for the
+  // selected model.
+  //
+  // Auto-mode only (#4965): `guided-flow.ts:dispatchWorkflow` also calls
+  // `selectAndApplyModel` with `isAutoMode=false`. Guided-flow has its own
+  // narrow/restore via discuss-tool-scoping (guided-flow.ts:587-622) and no
+  // baseline-clear hook of its own, so an unconditional restore here would
+  // resurrect an auto-era baseline on guided-flow dispatches — silently
+  // overwriting any tool changes made interactively between auto sessions.
+  // The baseline is structurally an auto-mode concept; gate it accordingly.
+  if (isAutoMode) restoreToolBaseline(pi);
+
   if (modelConfig) {
     const availableModels = ctx.modelRegistry.getAvailable();
     const modelPolicyTraceId = `model:${ctx.sessionManager.getSessionId()}:${Date.now()}`;
@@ -160,7 +260,16 @@ export async function selectAndApplyModel(
       ? extractTaskMetadata(unitId, basePath)
       : undefined;
 
+    let policyDenyReasons: Array<{ provider: string; modelId: string; reason: string }> = [];
     if (uokFlags.modelPolicy) {
+      // Use the workflow-spec required-tool subset for the unit type rather
+      // than the live `pi.getActiveTools()` snapshot (#4959).  The active set
+      // is poisoned by per-unit narrowing for narrow-API providers — using it
+      // as a hard gate promotes soft adaptation (adjustToolSet at line ~417)
+      // into a layering violation that throws before dispatch.  The smaller
+      // workflow-required subset reflects what the unit actually needs; soft
+      // adaptation post-selection still trims provider-incompatible tools.
+      const requiredTools = getRequiredWorkflowToolsForAutoUnit(unitType);
       const policy = applyModelPolicyFilter(
         availableModels,
         {
@@ -171,15 +280,18 @@ export async function selectAndApplyModel(
           taskMetadata: taskMetadataForPolicy,
           currentProvider: ctx.model?.provider,
           allowCrossProvider: routingConfig.cross_provider !== false,
-          requiredTools: pi.getActiveTools(),
+          requiredTools,
         },
       );
       routingEligibleModels = policy.eligible;
       policyAllowedModelKeys = new Set(
         policy.eligible.map((m) => `${m.provider.toLowerCase()}/${m.id.toLowerCase()}`),
       );
+      policyDenyReasons = policy.decisions
+        .filter((d) => !d.allowed)
+        .map((d) => ({ provider: d.provider, modelId: d.modelId, reason: d.reason }));
       if (routingEligibleModels.length === 0) {
-        throw new Error(`Model policy denied all candidate models for ${unitType}/${unitId}`);
+        throw new ModelPolicyDispatchBlockedError(unitType, unitId, policyDenyReasons);
       }
     }
 
@@ -235,7 +347,11 @@ export async function selectAndApplyModel(
         );
         const availableModelIds = routingEligibleModels.map(m => `${m.provider}/${m.id}`);
 
-        // Escalate tier on retry when escalate_on_failure is enabled (default: true)
+        // Escalate tier on retry when escalate_on_failure is enabled (default: true).
+        // #4973: Deterministic policy errors are short-circuited at the postUnit
+        // level (auto-post-unit.ts writes a placeholder and returns "continue"),
+        // so this code path only runs for legitimate model-quality retries where
+        // tier escalation is the right response.
         if (
           retryContext?.isRetry &&
           retryContext.previousTier &&
@@ -249,6 +365,17 @@ export async function selectAndApplyModel(
               `Tier escalation: ${retryContext.previousTier} → ${escalated} (retry after failure)`,
               "info",
             );
+          } else {
+            // #4973: Already at max tier — keep previousTier rather than letting
+            // fresh classification silently downgrade the model back to a lower tier.
+            // Without this, a light-start unit on retry 3 would revert to the light
+            // model after escalating to heavy on retries 1 and 2.
+            const tierOrder: Record<string, number> = { light: 0, standard: 1, heavy: 2 };
+            const prevOrder = tierOrder[retryContext.previousTier] ?? 0;
+            const freshOrder = tierOrder[classification.tier] ?? 0;
+            if (prevOrder > freshOrder) {
+              classification = { ...classification, tier: retryContext.previousTier as ComplexityTier, reason: "retained escalated tier from retry" };
+            }
           }
         }
 
@@ -443,7 +570,7 @@ export async function selectAndApplyModel(
     }
 
     if (uokFlags.modelPolicy && policyAllowedModelKeys && !attemptedPolicyEligible) {
-      throw new Error(`Model policy denied dispatch for ${unitType}/${unitId} before prompt send`);
+      throw new ModelPolicyDispatchBlockedError(unitType, unitId, policyDenyReasons);
     }
   } else if (autoModeStartModel) {
     // No model preference for this unit type — re-apply the model captured