gsd-pi 2.74.0 → 2.75.0-dev.063e5a3

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

@@ -14,9 +14,11 @@ import { debugLog } from "../debug-logger.js";
 import { PROJECT_FILES } from "../detection.js";
 import { MergeConflictError } from "../git-service.js";
 import { setCurrentPhase, clearCurrentPhase } from "../../shared/gsd-phase-state.js";
+import { pauseAutoForProviderError } from "../provider-error-pause.js";
+import { resumeAutoAfterProviderDelay } from "../bootstrap/provider-error-resume.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,10 +27,19 @@ 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";
 import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForAutoUnit, } from "../workflow-mcp.js";
+// ─── Session timeout auto-resume state ────────────────────────────────────────
+let consecutiveSessionTimeouts = 0;
+const MAX_SESSION_TIMEOUT_AUTO_RESUMES = 3;
+export function resetSessionTimeoutState() {
+    consecutiveSessionTimeouts = 0;
+}
 // ─── generateMilestoneReport ──────────────────────────────────────────────────
 /**
  * Resolve the base path for milestone reports.
@@ -46,6 +57,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 +120,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 +144,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 +200,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 +241,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 +302,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}`);
@@ -776,7 +904,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();
@@ -975,22 +1109,65 @@ 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" };
         }
-        // Session creation timeout (not a structural error): pause auto-mode
-        // and let the provider-error-resume timer handle recovery (#3767). This
-        // matches the provider-pause path — break out cleanly, don't hard-stop.
+        // Timeout category covers two distinct scenarios:
+        //   1. Session creation timeout (120s) — transient, auto-resume with backoff
+        //   2. Unit hard timeout (30min+) — stuck agent, pause for manual review
         // Structural errors (TypeError, is not a function) are NOT transient
         // and must hard-stop to avoid infinite retry loops.
         if (unitResult.errorContext?.isTransient &&
             unitResult.errorContext?.category === "timeout") {
-            ctx.ui.notify(`Session creation timed out for ${unitType} ${unitId}. Pausing auto-mode (recoverable).`, "warning");
-            debugLog("autoLoop", { phase: "session-timeout-pause", unitType, unitId });
+            const isSessionCreationTimeout = unitResult.errorContext.message?.includes("Session creation timed out");
+            if (isSessionCreationTimeout) {
+                consecutiveSessionTimeouts += 1;
+                const baseRetryAfterMs = 30_000;
+                const retryAfterMs = baseRetryAfterMs * 2 ** Math.max(0, consecutiveSessionTimeouts - 1);
+                const allowAutoResume = consecutiveSessionTimeouts <= MAX_SESSION_TIMEOUT_AUTO_RESUMES;
+                if (!allowAutoResume) {
+                    ctx.ui.notify(`Session creation timed out ${consecutiveSessionTimeouts} consecutive times for ${unitType} ${unitId}. Pausing for manual review.`, "warning");
+                }
+                debugLog("autoLoop", {
+                    phase: "session-timeout-pause",
+                    unitType, unitId,
+                    consecutiveSessionTimeouts,
+                    retryAfterMs,
+                    allowAutoResume,
+                });
+                const errorDetail = ` for ${unitType} ${unitId}`;
+                await pauseAutoForProviderError(ctx.ui, errorDetail, () => deps.pauseAuto(ctx, pi), {
+                    isRateLimit: false,
+                    isTransient: allowAutoResume,
+                    retryAfterMs,
+                    resume: allowAutoResume
+                        ? () => {
+                            void resumeAutoAfterProviderDelay(pi, ctx).catch((err) => {
+                                const message = err instanceof Error ? err.message : String(err);
+                                ctx.ui.notify(`Session timeout recovery failed: ${message}`, "error");
+                            });
+                        }
+                        : undefined,
+                });
+                await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+                await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+                return { action: "break", reason: "session-timeout" };
+            }
+            // Unit hard timeout (30min+): pause without auto-resume — stuck agent
+            ctx.ui.notify(`Unit timed out for ${unitType} ${unitId} (supervision may have failed). Pausing auto-mode.`, "warning");
+            debugLog("autoLoop", { phase: "unit-hard-timeout-pause", unitType, unitId });
             await deps.pauseAuto(ctx, pi);
-            return { action: "break", reason: "session-timeout" };
+            await deps.autoCommitUnit?.(s.basePath, unitType, unitId, ctx);
+            await emitCancelledUnitEnd(ic, unitType, unitId, unitStartSeq, unitResult.errorContext);
+            return { action: "break", reason: "unit-hard-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" });
@@ -1002,6 +1179,8 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     // Guard: stopAuto() may have nulled s.currentUnit via s.reset() while
     // this coroutine was suspended at `await runUnit(...)` (#2939).
     if (s.currentUnit) {
+        // Reset session timeout counter — any successful unit clears the slate
+        consecutiveSessionTimeouts = 0;
         await deps.closeoutUnit(ctx, s.basePath, unitType, unitId, s.currentUnit.startedAt, deps.buildSnapshotOpts(unitType, unitId));
     }
     // ── Zero tool-call guard (#1833, #2653) ──────────────────────────
@@ -1124,6 +1303,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",
@@ -1142,11 +1324,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) {
@@ -1199,6 +1385,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",
@@ -1230,5 +1419,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",
@@ -461,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

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

@@ -4,12 +4,14 @@
  * 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";
 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)
@@ -46,6 +48,7 @@ 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);
@@ -67,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,
@@ -75,15 +81,40 @@ 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) {
                 const primaryFlatRateCtx = buildFlatRateContext(primaryModel.provider, ctx, prefs);
                 if (isFlatRateProvider(primaryModel.provider, primaryFlatRateCtx)) {
@@ -110,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 &&
@@ -191,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);
@@ -255,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
@@ -359,10 +405,10 @@ export function isFlatRateProvider(provider, opts) {
  */
 export function buildFlatRateContext(provider, ctx, prefs) {
     let authMode;
-    const getAuthMode = ctx?.modelRegistry?.getProviderAuthMode;
-    if (typeof getAuthMode === "function") {
+    const registry = ctx?.modelRegistry;
+    if (registry && typeof registry.getProviderAuthMode === "function") {
         try {
-            const mode = getAuthMode(provider);
+            const mode = registry.getProviderAuthMode(provider);
             if (mode === "apiKey" || mode === "oauth" || mode === "externalCli" || mode === "none") {
                 authMode = mode;
             }