gsd-pi 2.77.0 → 2.78.0-dev.aeeb2ca00

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

@@ -18,10 +18,46 @@ 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, buildPlanMilestonePrompt, buildResearchSlicePrompt, buildPlanSlicePrompt, buildRefineSlicePrompt, buildExecuteTaskPrompt, buildCompleteSlicePrompt, buildCompleteMilestonePrompt, buildValidateMilestonePrompt, buildReplanSlicePrompt, buildRunUatPrompt, buildReassessRoadmapPrompt, buildRewriteDocsPrompt, buildReactiveExecutePrompt, buildGateEvaluatePrompt, buildParallelResearchSlicesPrompt, checkNeedsReassessment, checkNeedsRunUat, } from "./auto-prompts.js";
 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";
+let reassessmentChecker = checkNeedsReassessment;
+export function setReassessmentCheckerForTest(checker) {
+    const previous = reassessmentChecker;
+    reassessmentChecker = checker;
+    return () => {
+        reassessmentChecker = previous;
+    };
+}
+async function readUatGateVerdict(basePath, mid, sliceId) {
+    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, phase) {
     return {
         action: "stop",
@@ -155,6 +191,45 @@ export const DISPATCH_RULES = [
             };
         },
     },
+    {
+        // #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 }) => {
@@ -205,27 +280,29 @@ export const DISPATCH_RULES = [
             // 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;
+            // DB-first: prefer closed slices from DB; fall back to ROADMAP on disk.
+            let closedSliceIds;
             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)
+            for (const sliceId of closedSliceIds) {
+                const result = await readUatGateVerdict(basePath, mid, sliceId);
+                if (!result)
                     continue;
-                const content = await loadFile(resultFile);
-                if (!content)
-                    continue;
-                const verdict = extractVerdict(content);
-                const uatType = extractUatType(content);
-                if (verdict && !isAcceptableUatVerdict(verdict, uatType)) {
+                const { verdict, uatType } = result;
+                if (!isAcceptableUatVerdict(verdict, uatType)) {
                     return {
                         action: "stop",
                         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.`,
@@ -241,12 +318,16 @@ export const DISPATCH_RULES = [
         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 {
@@ -262,6 +343,12 @@ export const DISPATCH_RULES = [
         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",
@@ -279,6 +366,12 @@ export const DISPATCH_RULES = [
             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",
@@ -319,6 +412,30 @@ export const DISPATCH_RULES = [
             };
         },
     },
+    {
+        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",
+                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",
+            };
+        },
+    },
     {
         // Keep this rule before the single-slice research rule so the multi-slice
         // path wins whenever 2+ slices are ready.
@@ -328,6 +445,12 @@ export const DISPATCH_RULES = [
                 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");
             const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;
@@ -377,6 +500,9 @@ export const DISPATCH_RULES = [
             // 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;
@@ -658,22 +784,29 @@ export const DISPATCH_RULES = [
                     level: "error",
                 };
             }
-            // 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 });
                     const validationPath = join(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");
                 }
@@ -702,22 +835,13 @@ export const DISPATCH_RULES = [
                     return { action: "skip" };
                 }
             }
-            // 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)`);
+            let summaryOutcome = "unknown";
+            if (existingSummary) {
+                const summaryContent = await loadFile(existingSummary);
+                if (summaryContent) {
+                    summaryOutcome = classifyMilestoneSummaryContent(summaryContent);
                 }
-                catch (err) {
-                    logWarning("dispatch", `Failed to reconcile milestone ${mid} status: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                return { action: "skip" };
             }
             // Safety guard (#2675): block completion when VALIDATION verdict is
             // needs-remediation. The state machine treats needs-remediation as
@@ -749,7 +873,7 @@ export const DISPATCH_RULES = [
             // 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",
@@ -795,6 +919,45 @@ export const DISPATCH_RULES = [
             catch (err) { /* fall through — don't block on DB errors */
                 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/dist/resources/extensions/gsd/auto-loop.js

@@ -8,6 +8,6 @@
  */
 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";

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

@@ -13,6 +13,75 @@ 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 {
+    unitType;
+    unitId;
+    reasons;
+    constructor(unitType, unitId, reasons) {
+        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;
+    }
+}
+// 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();
+/**
+ * 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) {
+    TOOL_BASELINE.delete(pi);
+}
+function restoreToolBaseline(pi) {
+    const key = pi;
+    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, level) {
     if (!level)
         return;
@@ -86,6 +155,29 @@ autoModeStartThinkingLevel) {
         : resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode);
     let routing = null;
     let appliedModel = 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()}`;
@@ -114,7 +206,16 @@ autoModeStartThinkingLevel) {
         const taskMetadataForPolicy = unitType === "execute-task"
             ? extractTaskMetadata(unitId, basePath)
             : undefined;
+        let policyDenyReasons = [];
         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, {
                 basePath,
                 traceId: modelPolicyTraceId,
@@ -123,12 +224,15 @@ autoModeStartThinkingLevel) {
                 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);
             }
         }
         // Disable routing for flat-rate providers like GitHub Copilot (#3453).
@@ -169,7 +273,11 @@ autoModeStartThinkingLevel) {
             if (shouldClassify) {
                 let classification = classifyUnitComplexity(unitType, unitId, basePath, budgetPct, taskMetadataForPolicy);
                 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 &&
                     routingConfig.escalate_on_failure !== false) {
@@ -179,6 +287,18 @@ autoModeStartThinkingLevel) {
                         // Always notify on tier escalation — model changes should be visible (#3962)
                         ctx.ui.notify(`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 = { 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, reason: "retained escalated tier from retry" };
+                        }
+                    }
                 }
                 // Load user capability overrides from preferences (D-17: deep-merged with built-in profiles)
                 const capabilityOverrides = loadCapabilityOverrides(prefs ?? {});
@@ -335,7 +455,7 @@ autoModeStartThinkingLevel) {
             }
         }
         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) {