gsd-pi 2.73.1 → 2.74.0-dev.0306a2e

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

@@ -16,7 +16,7 @@ import { MergeConflictError } from "../git-service.js";
 import { setCurrentPhase, clearCurrentPhase } from "../../shared/gsd-phase-state.js";
 import { join, basename, dirname, parse as parsePath } from "node:path";
 import { existsSync, cpSync, readdirSync } from "node:fs";
-import { logWarning, logError } from "../workflow-logger.js";
+import { logWarning, logError, _resetLogs, drainLogs, drainAndSummarize, formatForNotification, hasAnyIssues, } from "../workflow-logger.js";
 import { gsdRoot } from "../paths.js";
 import { atomicWriteSync } from "../atomic-write.js";
 import { verifyExpectedArtifact, diagnoseExpectedArtifact, buildLoopRemediationSteps } from "../auto-recovery.js";
@@ -25,6 +25,9 @@ import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "
 import { getEligibleSlices } from "../slice-parallel-eligibility.js";
 import { startSliceParallel } from "../slice-parallel-orchestrator.js";
 import { isDbAvailable, getMilestoneSlices } from "../gsd-db.js";
+import { ensurePlanV2Graph } from "../uok/plan-v2.js";
+import { resolveUokFlags } from "../uok/flags.js";
+import { UokGateRunner } from "../uok/gate-runner.js";
 import { resetEvidence } from "../safety/evidence-collector.js";
 import { createCheckpoint, cleanupCheckpoint, rollbackToCheckpoint } from "../safety/git-checkpoint.js";
 import { resolveSafetyHarnessConfig } from "../safety/safety-harness.js";
@@ -46,6 +49,15 @@ export function _resolveReportBasePath(s) {
 export function _resolveDispatchGuardBasePath(s) {
     return s.originalBasePath || s.basePath;
 }
+const PLAN_V2_GATE_PHASES = new Set([
+    "executing",
+    "summarizing",
+    "validating-milestone",
+    "completing-milestone",
+]);
+function shouldRunPlanV2Gate(phase) {
+    return PLAN_V2_GATE_PHASES.has(phase);
+}
 /**
  * Generate and write an HTML milestone report snapshot.
  * Extracted from the milestone-transition block in autoLoop.
@@ -100,6 +112,22 @@ async function closeoutAndStop(ctx, pi, s, deps, reason) {
     }
     await deps.stopAuto(ctx, pi, reason);
 }
+async function emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, errorContext) {
+    ic.deps.emitJournalEvent({
+        ts: new Date().toISOString(),
+        flowId: ic.flowId,
+        seq: ic.nextSeq(),
+        eventType: "unit-end",
+        data: {
+            unitType,
+            unitId,
+            status: "cancelled",
+            artifactVerified: false,
+            ...(errorContext ? { errorContext } : {}),
+        },
+        causedBy: { flowId: ic.flowId, seq: unitStartSeq },
+    });
+}
 // ─── runPreDispatch ───────────────────────────────────────────────────────────
 /**
  * Phase 1: Pre-dispatch — resource guard, health gate, state derivation,
@@ -108,13 +136,52 @@ async function closeoutAndStop(ctx, pi, s, deps, reason) {
  */
 export async function runPreDispatch(ic, loopState) {
     const { ctx, pi, s, deps, prefs } = ic;
+    const uokFlags = resolveUokFlags(prefs);
+    const runPreDispatchGate = async (input) => {
+        if (!uokFlags.gates)
+            return;
+        const gateRunner = new UokGateRunner();
+        gateRunner.register({
+            id: input.gateId,
+            type: input.gateType,
+            execute: async () => ({
+                outcome: input.outcome,
+                failureClass: input.failureClass,
+                rationale: input.rationale,
+                findings: input.findings ?? "",
+            }),
+        });
+        await gateRunner.run(input.gateId, {
+            basePath: s.basePath,
+            traceId: `pre-dispatch:${ic.flowId}`,
+            turnId: `iter-${ic.iteration}`,
+            milestoneId: input.milestoneId ?? s.currentMilestoneId ?? undefined,
+            unitType: "pre-dispatch",
+            unitId: `iter-${ic.iteration}`,
+        });
+    };
     // Resource version guard
     const staleMsg = deps.checkResourcesStale(s.resourceVersionOnStart);
     if (staleMsg) {
+        await runPreDispatchGate({
+            gateId: "resource-version-guard",
+            gateType: "policy",
+            outcome: "fail",
+            failureClass: "policy",
+            rationale: "resource version guard blocked dispatch",
+            findings: staleMsg,
+        });
         await deps.stopAuto(ctx, pi, staleMsg);
         debugLog("autoLoop", { phase: "exit", reason: "resources-stale" });
         return { action: "break", reason: "resources-stale" };
     }
+    await runPreDispatchGate({
+        gateId: "resource-version-guard",
+        gateType: "policy",
+        outcome: "pass",
+        failureClass: "none",
+        rationale: "resource version guard passed",
+    });
     deps.invalidateAllCaches();
     s.lastPromptCharCount = undefined;
     s.lastBaselineCharCount = undefined;
@@ -125,13 +192,37 @@ export async function runPreDispatch(ic, loopState) {
             ctx.ui.notify(`Pre-dispatch: ${healthGate.fixesApplied.join(", ")}`, "info");
         }
         if (!healthGate.proceed) {
+            await runPreDispatchGate({
+                gateId: "pre-dispatch-health-gate",
+                gateType: "execution",
+                outcome: "manual-attention",
+                failureClass: "manual-attention",
+                rationale: "pre-dispatch health gate blocked dispatch",
+                findings: healthGate.reason,
+            });
             ctx.ui.notify(healthGate.reason || "Pre-dispatch health check failed — run /gsd doctor for details.", "error");
             await deps.pauseAuto(ctx, pi);
             debugLog("autoLoop", { phase: "exit", reason: "health-gate-failed" });
             return { action: "break", reason: "health-gate-failed" };
         }
+        await runPreDispatchGate({
+            gateId: "pre-dispatch-health-gate",
+            gateType: "execution",
+            outcome: "pass",
+            failureClass: "none",
+            rationale: "pre-dispatch health gate passed",
+            findings: healthGate.fixesApplied.length > 0 ? healthGate.fixesApplied.join(", ") : "",
+        });
     }
     catch (e) {
+        await runPreDispatchGate({
+            gateId: "pre-dispatch-health-gate",
+            gateType: "execution",
+            outcome: "manual-attention",
+            failureClass: "manual-attention",
+            rationale: "pre-dispatch health gate threw unexpectedly",
+            findings: String(e),
+        });
         logWarning("engine", "Pre-dispatch health gate threw unexpectedly", { error: String(e) });
     }
     // Sync project root artifacts into worktree
@@ -142,6 +233,32 @@ export async function runPreDispatch(ic, loopState) {
     }
     // Derive state
     let state = await deps.deriveState(s.basePath);
+    if (prefs?.uok?.plan_v2?.enabled && shouldRunPlanV2Gate(state.phase)) {
+        const compiled = ensurePlanV2Graph(s.basePath, state);
+        if (!compiled.ok) {
+            const reason = compiled.reason ?? "Plan v2 compilation failed";
+            await runPreDispatchGate({
+                gateId: "plan-v2-gate",
+                gateType: "policy",
+                outcome: "manual-attention",
+                failureClass: "manual-attention",
+                rationale: "plan v2 compile gate failed",
+                findings: reason,
+                milestoneId: state.activeMilestone?.id ?? undefined,
+            });
+            ctx.ui.notify(`Plan gate failed-closed: ${reason}`, "error");
+            await deps.pauseAuto(ctx, pi);
+            return { action: "break", reason: "plan-v2-gate-failed" };
+        }
+        await runPreDispatchGate({
+            gateId: "plan-v2-gate",
+            gateType: "policy",
+            outcome: "pass",
+            failureClass: "none",
+            rationale: "plan v2 compile gate passed",
+            milestoneId: state.activeMilestone?.id ?? undefined,
+        });
+    }
     deps.syncCmuxSidebar(prefs, state);
     let mid = state.activeMilestone?.id;
     let midTitle = state.activeMilestone?.title;
@@ -177,7 +294,10 @@ export async function runPreDispatch(ic, loopState) {
                         eligibleSlices: eligible.map(e => e.id),
                     });
                     ctx.ui.notify(`Slice-parallel: dispatching ${eligible.length} eligible slices for ${mid}.`, "info");
-                    const result = await startSliceParallel(s.basePath, mid, eligible, { maxWorkers: prefs.slice_parallel.max_workers ?? 2 });
+                    const result = await startSliceParallel(s.basePath, mid, eligible, {
+                        maxWorkers: prefs.slice_parallel.max_workers ?? 2,
+                        useExecutionGraph: uokFlags.executionGraph,
+                    });
                     if (result.started.length > 0) {
                         ctx.ui.notify(`Slice-parallel: started ${result.started.length} worker(s): ${result.started.join(", ")}.`, "info");
                         await deps.stopAuto(ctx, pi, `Slice-parallel dispatched for ${mid}`);
@@ -320,10 +440,13 @@ export async function runPreDispatch(ic, loopState) {
         }
         else if (state.phase === "blocked") {
             const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
-            await deps.stopAuto(ctx, pi, blockerMsg);
-            ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
-            deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention", basename(s.originalBasePath || s.basePath));
-            deps.logCmuxEvent(prefs, blockerMsg, "error");
+            // Pause instead of hard-stop so the session is resumable with `/gsd auto`.
+            // Hard-stop here was causing premature termination when slice dependencies
+            // were temporarily unresolvable (e.g. after reassessment added new slices).
+            await deps.pauseAuto(ctx, pi);
+            ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto to resume.`, "warning");
+            deps.sendDesktopNotification("GSD", blockerMsg, "warning", "attention", basename(s.originalBasePath || s.basePath));
+            deps.logCmuxEvent(prefs, blockerMsg, "warning");
         }
         else {
             const ids = incomplete.map((m) => m.id).join(", ");
@@ -392,13 +515,16 @@ export async function runPreDispatch(ic, loopState) {
         deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "terminal", data: { reason: "milestone-complete", milestoneId: mid } });
         return { action: "break", reason: "milestone-complete" };
     }
-    // Terminal: blocked
+    // Terminal: blocked — pause instead of hard-stop so the session is resumable.
     if (state.phase === "blocked") {
         const blockerMsg = `Blocked: ${state.blockers.join(", ")}`;
-        await closeoutAndStop(ctx, pi, s, deps, blockerMsg);
-        ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning");
-        deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention", basename(s.originalBasePath || s.basePath));
-        deps.logCmuxEvent(prefs, blockerMsg, "error");
+        if (s.currentUnit) {
+            await deps.closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, deps.buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
+        }
+        await deps.pauseAuto(ctx, pi);
+        ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto to resume.`, "warning");
+        deps.sendDesktopNotification("GSD", blockerMsg, "warning", "attention", basename(s.originalBasePath || s.basePath));
+        deps.logCmuxEvent(prefs, blockerMsg, "warning");
         debugLog("autoLoop", { phase: "exit", reason: "blocked" });
         deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "terminal", data: { reason: "blocked", blockers: state.blockers } });
         return { action: "break", reason: "blocked" };
@@ -770,7 +896,13 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         s.currentUnit.type === unitType &&
         s.currentUnit.id === unitId);
     const previousTier = s.currentUnitRouting?.tier;
+    // Scope workflow-logger buffer to this unit so post-finalize drains are
+    // per-unit. Without this, the module-level _buffer accumulates across every
+    // unit in the same Node process (see workflow-logger.ts module header).
+    _resetLogs();
     s.currentUnit = { type: unitType, id: unitId, startedAt: Date.now() };
+    s.lastGitActionFailure = null;
+    s.lastGitActionStatus = null;
     setCurrentPhase(unitType);
     s.lastToolInvocationError = null; // #2883: clear stale error from previous unit
     const unitStartSeq = ic.nextSeq();
@@ -969,6 +1101,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         // Provider-error pause: pauseAuto already handled cleanup and scheduled
         // recovery. Don't hard-stop — just break out of the loop (#2762).
         if (unitResult.errorContext?.category === "provider") {
+            await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
             debugLog("autoLoop", { phase: "exit", reason: "provider-pause", isTransient: unitResult.errorContext.isTransient });
             return { action: "break", reason: "provider-pause" };
         }
@@ -982,9 +1115,16 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
             ctx.ui.notify(`Session creation timed out for ${unitType} ${unitId}. Pausing auto-mode (recoverable).`, "warning");
             debugLog("autoLoop", { phase: "session-timeout-pause", unitType, unitId });
             await deps.pauseAuto(ctx, pi);
+            await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+            await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
             return { action: "break", reason: "session-timeout" };
         }
         // All other cancelled states (structural errors, non-transient failures): hard stop
+        if (s.currentUnit) {
+            await deps.closeoutUnit(ctx, s.basePath, unitType, unitId, s.currentUnit.startedAt, deps.buildSnapshotOpts(unitType, unitId));
+        }
+        await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+        await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
         ctx.ui.notify(`Session creation failed for ${unitType} ${unitId}: ${unitResult.errorContext?.message ?? "unknown"}. Stopping auto-mode.`, "warning");
         await deps.stopAuto(ctx, pi, `Session creation failed: ${unitResult.errorContext?.message ?? "unknown"}`);
         debugLog("autoLoop", { phase: "exit", reason: "session-failed" });
@@ -1118,6 +1258,9 @@ export async function runFinalize(ic, iterData, loopState, sidecarItem) {
         // cannot mutate state for the next unit (#3757).
         s.currentUnit = null;
         clearCurrentPhase();
+        // Drop any logger entries from the timed-out unit so they don't bleed
+        // into the next iteration's drain.
+        drainLogs();
         loopState.consecutiveFinalizeTimeouts++;
         debugLog("autoLoop", {
             phase: "pre-verification-timeout",
@@ -1136,11 +1279,15 @@ export async function runFinalize(ic, iterData, loopState, sidecarItem) {
     }
     const preResult = preResultGuard.value;
     if (preResult === "dispatched") {
+        const dispatchedReason = s.lastGitActionFailure
+            ? "git-closeout-failure"
+            : "pre-verification-dispatched";
         debugLog("autoLoop", {
             phase: "exit",
-            reason: "pre-verification-dispatched",
+            reason: dispatchedReason,
+            gitError: s.lastGitActionFailure ?? undefined,
         });
-        return { action: "break", reason: "pre-verification-dispatched" };
+        return { action: "break", reason: dispatchedReason };
     }
     if (preResult === "retry") {
         if (sidecarItem) {
@@ -1193,6 +1340,9 @@ export async function runFinalize(ic, iterData, loopState, sidecarItem) {
         // cannot mutate state for the next unit (#3757).
         s.currentUnit = null;
         clearCurrentPhase();
+        // Drop any logger entries from the timed-out unit so they don't bleed
+        // into the next iteration's drain.
+        drainLogs();
         loopState.consecutiveFinalizeTimeouts++;
         debugLog("autoLoop", {
             phase: "post-verification-timeout",
@@ -1224,5 +1374,15 @@ export async function runFinalize(ic, iterData, loopState, sidecarItem) {
     }
     // Both pre and post verification completed without timeout — reset counter
     loopState.consecutiveFinalizeTimeouts = 0;
+    // Surface accumulated workflow-logger issues for this unit to the user.
+    // Warnings/errors logged during the unit are buffered in the logger and
+    // drained here so the user sees a single consolidated post-unit alert.
+    if (hasAnyIssues()) {
+        const { logs } = drainAndSummarize();
+        if (logs.length > 0) {
+            const severity = logs.some((e) => e.severity === "error") ? "error" : "warning";
+            ctx.ui.notify(formatForNotification(logs), severity);
+        }
+    }
     return { action: "next", data: undefined };
 }

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

@@ -52,6 +52,8 @@ export class AutoSession {
     continueHereHandle = null;
     // ── Current unit ─────────────────────────────────────────────────────────
     currentUnit = null;
+    currentTraceId = null;
+    currentTurnId = null;
     currentUnitRouting = null;
     currentMilestoneId = null;
     // ── Model state ──────────────────────────────────────────────────────────
@@ -79,6 +81,10 @@ export class AutoSession {
     /** Set when a GSD tool execution ends with isError due to malformed/truncated
      *  JSON arguments. Checked by postUnitPreVerification to break retry loops. */
     lastToolInvocationError = null;
+    /** Set when turn-level git action fails during closeout. */
+    lastGitActionFailure = null;
+    /** Last turn-level git action status captured during finalize. */
+    lastGitActionStatus = null;
     // ── Isolation degradation ────────────────────────────────────────────
     /** Set to true when worktree creation fails; prevents merge of nonexistent branch. */
     isolationDegraded = false;
@@ -157,6 +163,8 @@ export class AutoSession {
         this.unitRecoveryCount.clear();
         // Unit
         this.currentUnit = null;
+        this.currentTraceId = null;
+        this.currentTurnId = null;
         this.currentUnitRouting = null;
         this.currentMilestoneId = null;
         // Model
@@ -185,6 +193,8 @@ export class AutoSession {
         this.rewriteAttemptCount = 0;
         this.consecutiveCompleteBootstraps = 0;
         this.lastToolInvocationError = null;
+        this.lastGitActionFailure = null;
+        this.lastGitActionStatus = null;
         this.isolationDegraded = false;
         this.milestoneMergedInPhases = false;
         this.checkpointSha = null;

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

@@ -19,6 +19,8 @@ import { join } from "node:path";
 import { hasImplementationArtifacts } from "./auto-recovery.js";
 import { buildDiscussMilestonePrompt, buildResearchMilestonePrompt, buildPlanMilestonePrompt, buildResearchSlicePrompt, buildPlanSlicePrompt, 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";
 function missingSliceStop(mid, phase) {
     return {
         action: "stop",
@@ -216,7 +218,12 @@ export const DISPATCH_RULES = [
     {
         name: "reassess-roadmap (post-completion)",
         match: async ({ state, mid, midTitle, basePath, prefs }) => {
-            if (prefs?.phases?.skip_reassess || !prefs?.phases?.reassess_after_slice)
+            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;
+            if (!reassessEnabled)
                 return null;
             const needsReassess = await checkNeedsReassessment(basePath, mid, state);
             if (!needsReassess)
@@ -456,7 +463,15 @@ export const DISPATCH_RULES = [
                 // Only activate reactive dispatch when >1 task is ready
                 if (readyIds.length <= 1)
                     return null;
-                const selected = chooseNonConflictingSubset(readyIds, graph, maxParallel, new Set());
+                const uokFlags = resolveUokFlags(prefs);
+                const selected = uokFlags.executionGraph
+                    ? selectReactiveDispatchBatch({
+                        graph,
+                        readyIds,
+                        maxParallel,
+                        inFlightOutputs: new Set(),
+                    }).selected
+                    : chooseNonConflictingSubset(readyIds, graph, maxParallel, new Set());
                 if (selected.length <= 1)
                     return null;
                 // Log graph metrics for observability
@@ -710,11 +725,14 @@ export async function resolveDispatch(ctx) {
             return result;
         }
     }
-    // No rule matched — unhandled phase
+    // No rule matched — unhandled phase.
+    // Use level "warning" so the loop pauses (resumable) instead of hard-stopping.
+    // Hard-stop here was causing premature termination for transient phase gaps
+    // (e.g. after reassessment modifies the roadmap and state needs re-derivation).
     return {
         action: "stop",
         reason: `Unhandled phase "${ctx.state.phase}" — run /gsd doctor to diagnose.`,
-        level: "info",
+        level: "warning",
         matchedRule: "<no-match>",
     };
 }

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

@@ -4,15 +4,15 @@
  * and fallback chains.
  */
 import { resolveModelWithFallbacksForUnit, resolveDynamicRoutingConfig } from "./preferences.js";
-import { classifyUnitComplexity, tierLabel } from "./complexity-classifier.js";
+import { classifyUnitComplexity, extractTaskMetadata, tierLabel } from "./complexity-classifier.js";
 import { resolveModelForComplexity, escalateTier, getEligibleModels, loadCapabilityOverrides, adjustToolSet } from "./model-router.js";
 import { getLedger, getProjectTotals } from "./metrics.js";
 import { unitPhaseLabel } from "./auto-dashboard.js";
 import { getSessionModelOverride } from "./session-model-override.js";
-export function resolvePreferredModelConfig(unitType, autoModeStartModel, 
-/** When false, only return explicit per-phase model configs — do not
- *  synthesize a routing ceiling from dynamic_routing.tier_models (#3962). */
-isAutoMode = true) {
+import { logWarning } from "./workflow-logger.js";
+import { resolveUokFlags } from "./uok/flags.js";
+import { applyModelPolicyFilter } from "./uok/model-policy.js";
+export function resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode = true) {
     const explicitConfig = resolveModelWithFallbacksForUnit(unitType);
     if (explicitConfig)
         return explicitConfig;
@@ -24,7 +24,7 @@ isAutoMode = true) {
     if (!routingConfig.enabled || !routingConfig.tier_models)
         return undefined;
     // Don't synthesize a routing config for flat-rate providers (#3453).
-    if (autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider))
+    if (autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider, autoModeStartModel.flatRateCtx))
         return undefined;
     const ceilingModel = routingConfig.tier_models.heavy
         ?? (autoModeStartModel ? `${autoModeStartModel.provider}/${autoModeStartModel.id}` : undefined);
@@ -48,9 +48,21 @@ export async function selectAndApplyModel(ctx, pi, unitType, unitId, basePath, p
 isAutoMode = true, 
 /** Explicit /gsd model pin captured at bootstrap for long-running auto loops. */
 sessionModelOverride) {
+    const uokFlags = resolveUokFlags(prefs);
     const effectiveSessionModelOverride = sessionModelOverride === undefined
         ? getSessionModelOverride(ctx.sessionManager.getSessionId())
         : (sessionModelOverride ?? undefined);
+    // Enrich the start model with a flat-rate context up front so routing
+    // synthesis and the dispatch-time guard see the same signals (built-in
+    // list + user `flat_rate_providers` preference + externalCli auto-
+    // detection).  The dispatch-time primary-model check below builds its
+    // own per-provider context when it has a resolved primary model.
+    if (autoModeStartModel) {
+        autoModeStartModel = {
+            ...autoModeStartModel,
+            flatRateCtx: buildFlatRateContext(autoModeStartModel.provider, ctx, prefs),
+        };
+    }
     const modelConfig = effectiveSessionModelOverride
         ? undefined
         : resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode);
@@ -58,6 +70,9 @@ sessionModelOverride) {
     let appliedModel = null;
     if (modelConfig) {
         const availableModels = ctx.modelRegistry.getAvailable();
+        const modelPolicyTraceId = `model:${ctx.sessionManager.getSessionId()}:${Date.now()}`;
+        const modelPolicyTurnId = `${unitType}:${unitId}`;
+        let policyAllowedModelKeys = null;
         // ─── Dynamic Model Routing ─────────────────────────────────────────
         // Dynamic routing (complexity-based downgrading) only applies in auto-mode.
         // Interactive/guided-flow dispatches use the user's session model directly,
@@ -66,22 +81,48 @@ sessionModelOverride) {
         if (!isAutoMode) {
             routingConfig.enabled = false;
         }
+        // burn-max defaults to quality-first dispatch (no downgrade routing).
+        if (prefs?.token_profile === "burn-max") {
+            routingConfig.enabled = false;
+        }
         let effectiveModelConfig = modelConfig;
         let routingTierLabel = "";
+        let routingEligibleModels = availableModels;
+        const taskMetadataForPolicy = unitType === "execute-task"
+            ? extractTaskMetadata(unitId, basePath)
+            : undefined;
+        if (uokFlags.modelPolicy) {
+            const policy = applyModelPolicyFilter(availableModels, {
+                basePath,
+                traceId: modelPolicyTraceId,
+                turnId: modelPolicyTurnId,
+                unitType,
+                taskMetadata: taskMetadataForPolicy,
+                currentProvider: ctx.model?.provider,
+                allowCrossProvider: routingConfig.cross_provider !== false,
+                requiredTools: pi.getActiveTools(),
+            });
+            routingEligibleModels = policy.eligible;
+            policyAllowedModelKeys = new Set(policy.eligible.map((m) => `${m.provider.toLowerCase()}/${m.id.toLowerCase()}`));
+            if (routingEligibleModels.length === 0) {
+                throw new Error(`Model policy denied all candidate models for ${unitType}/${unitId}`);
+            }
+        }
         // Disable routing for flat-rate providers like GitHub Copilot (#3453).
         // All models cost the same per request, so downgrading to a cheaper
         // model provides no cost benefit — it only degrades quality.
         // Fail-closed: if primary model can't be resolved, fall back to
         // provider-level signals rather than allowing unwanted downgrades.
         if (routingConfig.enabled) {
-            const primaryModel = resolveModelId(modelConfig.primary, availableModels, ctx.model?.provider);
+            const primaryModel = resolveModelId(modelConfig.primary, routingEligibleModels, ctx.model?.provider);
             if (primaryModel) {
-                if (isFlatRateProvider(primaryModel.provider)) {
+                const primaryFlatRateCtx = buildFlatRateContext(primaryModel.provider, ctx, prefs);
+                if (isFlatRateProvider(primaryModel.provider, primaryFlatRateCtx)) {
                     routingConfig.enabled = false;
                 }
             }
-            else if ((autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider))
-                || (ctx.model?.provider && isFlatRateProvider(ctx.model.provider))) {
+            else if ((autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider, autoModeStartModel.flatRateCtx))
+                || (ctx.model?.provider && isFlatRateProvider(ctx.model.provider, buildFlatRateContext(ctx.model.provider, ctx, prefs)))) {
                 // Primary model unresolvable but provider signals indicate flat-rate —
                 // disable routing to prevent quality degradation.
                 routingConfig.enabled = false;
@@ -100,8 +141,8 @@ sessionModelOverride) {
             const isHook = unitType.startsWith("hook/");
             const shouldClassify = !isHook || routingConfig.hooks !== false;
             if (shouldClassify) {
-                let classification = classifyUnitComplexity(unitType, unitId, basePath, budgetPct);
-                const availableModelIds = availableModels.map(m => m.id);
+                let classification = classifyUnitComplexity(unitType, unitId, basePath, budgetPct, taskMetadataForPolicy);
+                const availableModelIds = routingEligibleModels.map(m => m.id);
                 // Escalate tier on retry when escalate_on_failure is enabled (default: true)
                 if (retryContext?.isRetry &&
                     retryContext.previousTier &&
@@ -181,13 +222,25 @@ sessionModelOverride) {
             }
         }
         const modelsToTry = [effectiveModelConfig.primary, ...effectiveModelConfig.fallbacks];
+        let attemptedPolicyEligible = false;
         for (const modelId of modelsToTry) {
-            const model = resolveModelId(modelId, availableModels, ctx.model?.provider);
+            const resolutionPool = uokFlags.modelPolicy ? routingEligibleModels : availableModels;
+            const model = resolveModelId(modelId, resolutionPool, ctx.model?.provider);
             if (!model) {
                 if (verbose)
                     ctx.ui.notify(`Model ${modelId} not found, trying fallback.`, "info");
                 continue;
             }
+            if (policyAllowedModelKeys) {
+                const key = `${model.provider.toLowerCase()}/${model.id.toLowerCase()}`;
+                if (!policyAllowedModelKeys.has(key)) {
+                    if (verbose) {
+                        ctx.ui.notify(`Model policy denied ${model.provider}/${model.id}; trying fallback.`, "warning");
+                    }
+                    continue;
+                }
+                attemptedPolicyEligible = true;
+            }
             // Warn if the ID is ambiguous across providers
             if (!modelId.includes("/")) {
                 const providers = availableModels.filter(m => m.id === modelId).map(m => m.provider);
@@ -245,6 +298,9 @@ sessionModelOverride) {
                 }
             }
         }
+        if (uokFlags.modelPolicy && policyAllowedModelKeys && !attemptedPolicyEligible) {
+            throw new Error(`Model policy denied dispatch for ${unitType}/${unitId} before prompt send`);
+        }
     }
     else if (autoModeStartModel) {
         // No model preference for this unit type — re-apply the model captured
@@ -331,7 +387,40 @@ export function resolveModelId(modelId, availableModels, currentProvider) {
  * Uses case-insensitive matching with alias support to prevent fail-open on
  * provider naming variations (e.g. "copilot" vs "github-copilot").
  */
-const FLAT_RATE_PROVIDERS = new Set(["github-copilot", "copilot", "claude-code"]);
-export function isFlatRateProvider(provider) {
-    return FLAT_RATE_PROVIDERS.has(provider.toLowerCase());
+const BUILTIN_FLAT_RATE = new Set(["github-copilot", "copilot", "claude-code"]);
+export function isFlatRateProvider(provider, opts) {
+    const p = provider.toLowerCase();
+    if (BUILTIN_FLAT_RATE.has(p))
+        return true;
+    if (opts?.userFlatRate?.some(id => id.toLowerCase() === p))
+        return true;
+    if (opts?.authMode === "externalCli")
+        return true;
+    return false;
+}
+/**
+ * Build a FlatRateContext for a given provider from live runtime state.
+ * Safe to call when ctx or prefs are undefined — missing pieces are
+ * treated as "no signal".
+ */
+export function buildFlatRateContext(provider, ctx, prefs) {
+    let authMode;
+    const getAuthMode = ctx?.modelRegistry?.getProviderAuthMode;
+    if (typeof getAuthMode === "function") {
+        try {
+            const mode = getAuthMode(provider);
+            if (mode === "apiKey" || mode === "oauth" || mode === "externalCli" || mode === "none") {
+                authMode = mode;
+            }
+        }
+        catch (err) {
+            // Registry lookup failure must never break flat-rate detection —
+            // fall through with authMode undefined and surface the cause.
+            logWarning("dispatch", `flat-rate auth-mode lookup failed for ${provider}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return {
+        authMode,
+        userFlatRate: prefs?.flat_rate_providers,
+    };
 }