@open-agent-toolkit/cli 0.1.45 → 0.1.48

package/dist/commands/project/dispatch-ceiling/index.js

@@ -4,13 +4,14 @@ import { buildCommandContext, } from '../../../app/command-context.js';
 import { getFrontmatterBlock } from '../../shared/frontmatter.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { compileDispatchPolicyPreset, } from '../../../config/dispatch-ceiling-preset.js';
-import { resolveActiveProject, VALID_CLAUDE_DISPATCH_CEILINGS, VALID_CODEX_DISPATCH_CEILINGS, VALID_DISPATCH_MATRIX_TIERS, VALID_MANAGED_DISPATCH_POLICIES, } from '../../../config/oat-config.js';
+import { getDispatchPolicyChoices, managedDispatchPolicyValueList, renderDispatchPolicyChoicesMarkdown, } from '../../../config/dispatch-policy-options.js';
+import { resolveActiveProject, VALID_CLAUDE_DISPATCH_CEILINGS, VALID_CODEX_DISPATCH_CEILINGS, VALID_DISPATCH_MATRIX_TIERS, VALID_MANAGED_DISPATCH_POLICIES, isWorkflowDispatchCandidateLadder, isWorkflowDispatchFallbackRoute, toWorkflowDispatchCandidateLadder, validateDispatchRouteTarget, } from '../../../config/oat-config.js';
 import { resolveEffectiveConfig, } from '../../../config/resolve.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
 import TOML from '@iarna/toml';
-import { getCeilingAdapter, } from '../../../providers/ceiling/registry.js';
+import { getCeilingAdapter, isDirectDispatchRoleName, CLAUDE_TIER_ORDER, } from '../../../providers/ceiling/registry.js';
 import { classifyModelFamily, } from '../../../providers/identity/family.js';
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import YAML from 'yaml';
 const CODEX_VALUES = [
     ...VALID_CODEX_DISPATCH_CEILINGS,
@@ -84,6 +85,8 @@ function sourceLabel(source) {
             return 'environment';
         case 'project-state':
             return 'project state';
+        case 'invocation':
+            return 'explicit invocation';
         default:
             return 'none';
     }
@@ -106,7 +109,7 @@ function isValidManagedPolicy(value) {
         VALID_MANAGED_DISPATCH_POLICIES.includes(value));
 }
 function validManagedPolicyList() {
-    return VALID_MANAGED_DISPATCH_POLICIES.join(', ');
+    return managedDispatchPolicyValueList(', ');
 }
 function validProviderValueList(provider) {
     return providerValueOrder(provider)?.join(', ') ?? 'none';
@@ -150,11 +153,7 @@ function normalizeProjectMatrixRouteTarget(value) {
     }
     return Object.keys(target).length > 0 ? target : undefined;
 }
-function normalizeProjectMatrixCell(provider, value) {
-    const bareValue = normalizeProjectMatrixBareValue(provider, value);
-    if (bareValue !== undefined) {
-        return bareValue;
-    }
+function normalizeProjectMatrixRoute(provider, value) {
     if (!Array.isArray(value) || value.length === 0) {
         return undefined;
     }
@@ -172,6 +171,34 @@ function normalizeProjectMatrixCell(provider, value) {
     }
     return route.length > 0 ? route : undefined;
 }
+function normalizeProjectMatrixCandidate(provider, value) {
+    const bareValue = normalizeProjectMatrixBareValue(provider, value);
+    if (bareValue !== undefined) {
+        return bareValue;
+    }
+    if (isWorkflowDispatchFallbackRoute(value)) {
+        const route = normalizeProjectMatrixRoute(provider, value.route);
+        return route ? { route } : undefined;
+    }
+    return normalizeProjectMatrixRouteTarget(value);
+}
+function normalizeProjectMatrixCell(provider, value) {
+    const bareValue = normalizeProjectMatrixBareValue(provider, value);
+    if (bareValue !== undefined) {
+        return bareValue;
+    }
+    if (isWorkflowDispatchCandidateLadder(value)) {
+        const candidates = [];
+        for (const candidate of value.candidates) {
+            const normalized = normalizeProjectMatrixCandidate(provider, candidate);
+            if (normalized !== undefined) {
+                candidates.push(normalized);
+            }
+        }
+        return candidates.length > 0 ? { candidates } : undefined;
+    }
+    return normalizeProjectMatrixRoute(provider, value);
+}
 function normalizeProjectMatrixProviderValue(provider, value) {
     const bareValue = normalizeProjectMatrixBareValue(provider, value);
     if (bareValue !== undefined) {
@@ -230,6 +257,22 @@ function policyTier(policy) {
         ? policy
         : null;
 }
+function uncappedPreferredTier(provider, role, preferredValue) {
+    if (provider !== 'codex' || role === 'reviewer' || preferredValue === null) {
+        return null;
+    }
+    if (VALID_DISPATCH_MATRIX_TIERS.includes(preferredValue)) {
+        return preferredValue;
+    }
+    let matchedTier = null;
+    for (const tier of VALID_DISPATCH_MATRIX_TIERS) {
+        const compiledValue = compiledPolicyValueForProvider(provider, compileDispatchPolicyPreset(tier));
+        if (compiledValue === preferredValue) {
+            matchedTier = tier;
+        }
+    }
+    return matchedTier;
+}
 function dispatchValueFromRouteTarget(target) {
     const adapter = getCeilingAdapter(target.harness);
     if (adapter.mechanism === 'pinned-variant') {
@@ -276,12 +319,25 @@ function resolveRouteMatrixCell(provider, route, escalationLevel, cellSource) {
     const target = typeof entry === 'string'
         ? routeTargetFromBareValue(provider, entry, routeIndex, route.length)
         : routeTargetFromObject(provider, entry, routeIndex, route.length);
-    const value = typeof entry === 'string' ? entry : dispatchValueFromRouteTarget(target);
+    const targetValidation = typeof entry === 'string'
+        ? { valid: true }
+        : validateDispatchRouteTarget(provider, entry);
+    const value = targetValidation.valid
+        ? typeof entry === 'string'
+            ? entry
+            : dispatchValueFromRouteTarget(target)
+        : null;
+    const warnings = targetValidation.valid
+        ? []
+        : [
+            `Ignoring incomplete Codex dispatch target at route index ${routeIndex}: ${targetValidation.reason}`,
+        ];
     return {
         value,
         cellSource,
         target,
         selectionBranch: routeIndex > 0 ? 'escalation-target' : 'matrix-pinned',
+        warnings,
     };
 }
 function resolveProviderCellFromValue(provider, providerValue, tier, cellSource, escalationLevel) {
@@ -294,6 +350,7 @@ function resolveProviderCellFromValue(provider, providerValue, tier, cellSource,
             cellSource,
             target: null,
             selectionBranch: 'prompt-persisted',
+            warnings: [],
         };
     }
     if (tier === null) {
@@ -309,8 +366,22 @@ function resolveProviderCellFromValue(provider, providerValue, tier, cellSource,
             cellSource,
             target: null,
             selectionBranch: 'matrix-pinned',
+            warnings: [],
         };
     }
+    if (isWorkflowDispatchCandidateLadder(cell)) {
+        const ceiling = cell.candidates.at(-1);
+        if (ceiling === undefined) {
+            return null;
+        }
+        if (typeof ceiling === 'string') {
+            return resolveRouteMatrixCell(provider, [ceiling], escalationLevel, cellSource);
+        }
+        const route = isWorkflowDispatchFallbackRoute(ceiling)
+            ? ceiling.route
+            : [ceiling];
+        return resolveRouteMatrixCell(provider, route, escalationLevel, cellSource);
+    }
     return resolveRouteMatrixCell(provider, cell, escalationLevel, cellSource);
 }
 function resolveProviderMatrixCell(provider, tier, resolvedConfig, projectMatrix, escalationLevel) {
@@ -338,6 +409,212 @@ function resolveProviderMatrixCell(provider, tier, resolvedConfig, projectMatrix
     }
     return selected;
 }
+function resolveProviderMatrixCellDefinition(provider, tier, resolvedConfig, projectMatrix) {
+    let selected = null;
+    const layers = [
+        {
+            source: 'user-config',
+            providers: resolvedConfig.user.workflow?.dispatchCeiling?.providers,
+        },
+        {
+            source: 'repo-config',
+            providers: resolvedConfig.shared.workflow?.dispatchCeiling?.providers,
+        },
+        {
+            source: 'local-config',
+            providers: resolvedConfig.local.workflow?.dispatchCeiling?.providers,
+        },
+        { source: 'project-state', providers: projectMatrix },
+    ];
+    for (const layer of layers) {
+        const providerValue = layer.providers?.[provider];
+        if (typeof providerValue === 'string') {
+            selected = null;
+            continue;
+        }
+        const cell = providerValue?.[tier];
+        if (cell !== undefined) {
+            selected = { cell, cellSource: layer.source };
+        }
+    }
+    return selected;
+}
+function candidateRoute(candidate) {
+    return isWorkflowDispatchFallbackRoute(candidate)
+        ? candidate.route
+        : [candidate];
+}
+function candidatePrimaryTarget(provider, tier, candidate) {
+    const route = candidateRoute(candidate);
+    const entry = route[0];
+    if (entry === undefined) {
+        throw new Error(`Malformed ${provider} candidate ordering in ${tier}: fallback routes cannot be empty.`);
+    }
+    if (typeof entry !== 'string') {
+        const validation = validateDispatchRouteTarget(provider, entry);
+        if (!validation.valid) {
+            throw new Error(`Malformed ${provider} candidate ordering in ${tier}: ${validation.reason}`);
+        }
+    }
+    const target = typeof entry === 'string'
+        ? routeTargetFromBareValue(provider, entry, 0, route.length)
+        : routeTargetFromObject(provider, entry, 0, route.length);
+    if (target.model && isDirectDispatchRoleName(target.model)) {
+        throw new Error(`Malformed ${provider} candidate ordering in ${tier}: direct dispatch role names are not candidate models.`);
+    }
+    const targetAdapter = getCeilingAdapter(target.harness);
+    if (targetAdapter.mechanism === 'pinned-variant' &&
+        (!target.model ||
+            !target.effort ||
+            !CODEX_VALUES.includes(target.effort))) {
+        throw new Error(`Malformed ${provider} candidate ordering in ${tier}: Codex candidates require a model and supported effort.`);
+    }
+    if (targetAdapter.mechanism === 'model-arg' && !target.model) {
+        throw new Error(`Malformed ${provider} candidate ordering in ${tier}: model-argument candidates require a model.`);
+    }
+    return target;
+}
+function candidateTargetKey(target) {
+    return JSON.stringify([
+        target.harness,
+        target.model ?? null,
+        target.effort ?? null,
+    ]);
+}
+function assertCandidateOrder(provider, tier, ladder) {
+    if (ladder.candidates.length === 0) {
+        throw new Error(`Malformed ${provider} candidate ordering in ${tier}: candidates cannot be empty.`);
+    }
+    const targets = [];
+    const seen = new Set();
+    let previousClaudeRank = null;
+    const codexRanksByModel = new Map();
+    for (const candidate of ladder.candidates) {
+        const target = candidatePrimaryTarget(provider, tier, candidate);
+        const key = candidateTargetKey(target);
+        if (seen.has(key)) {
+            throw new Error(`Malformed ${provider} candidate ordering in ${tier}: duplicate candidate ${key}.`);
+        }
+        seen.add(key);
+        if (target.harness === 'claude' && target.model) {
+            const rank = CLAUDE_TIER_ORDER.indexOf(target.model);
+            if (rank < 0) {
+                throw new Error(`Malformed ${provider} candidate ordering in ${tier}: unsupported Claude model ${JSON.stringify(target.model)}.`);
+            }
+            if (previousClaudeRank !== null && rank < previousClaudeRank) {
+                throw new Error(`Malformed ${provider} candidate ordering in ${tier}: Claude candidates must be nondecreasing.`);
+            }
+            previousClaudeRank = rank;
+        }
+        if (target.harness === 'codex' && target.model && target.effort) {
+            const rank = CODEX_VALUES.indexOf(target.effort);
+            const previousRank = codexRanksByModel.get(target.model);
+            if (previousRank !== undefined && rank < previousRank) {
+                throw new Error(`Malformed ${provider} candidate ordering in ${tier}: Codex efforts for ${target.model} must be nondecreasing.`);
+            }
+            codexRanksByModel.set(target.model, rank);
+        }
+        targets.push(target);
+    }
+    return targets;
+}
+function assertTierCeilingsNondecreasing(provider, previous, current, tier) {
+    if (!previous || previous.harness !== current.harness) {
+        return;
+    }
+    if (current.harness === 'claude' &&
+        previous.model &&
+        current.model &&
+        CLAUDE_TIER_ORDER.indexOf(current.model) <
+            CLAUDE_TIER_ORDER.indexOf(previous.model)) {
+        throw new Error(`Malformed ${provider} candidate ordering in ${tier}: named tier ceilings must be nondecreasing.`);
+    }
+    if (current.harness === 'codex' &&
+        previous.model === current.model &&
+        previous.effort &&
+        current.effort &&
+        CODEX_VALUES.indexOf(current.effort) <
+            CODEX_VALUES.indexOf(previous.effort)) {
+        throw new Error(`Malformed ${provider} candidate ordering in ${tier}: named tier ceilings must be nondecreasing.`);
+    }
+}
+function requestedCandidateMatches(provider, requested, target) {
+    if (target.harness !== provider || target.model !== requested.model) {
+        return false;
+    }
+    return provider !== 'codex' || target.effort === requested.effort;
+}
+function formatRequestedCandidate(provider, requested) {
+    return provider === 'codex'
+        ? `${requested.model}/${requested.effort}`
+        : requested.model;
+}
+function resolveRequestedMatrixCandidate(provider, requested, ceilingTier, resolvedConfig, projectMatrix, escalationLevel) {
+    const ceilingIndex = ceilingTier === null
+        ? VALID_DISPATCH_MATRIX_TIERS.length - 1
+        : VALID_DISPATCH_MATRIX_TIERS.indexOf(ceilingTier);
+    let ceilingCellFound = ceilingTier === null;
+    let previousCeiling = null;
+    let allowedMatch;
+    let foundAboveCeiling = false;
+    for (const [tierIndex, tier] of VALID_DISPATCH_MATRIX_TIERS.entries()) {
+        const definition = resolveProviderMatrixCellDefinition(provider, tier, resolvedConfig, projectMatrix);
+        if (!definition) {
+            continue;
+        }
+        if (tier === ceilingTier) {
+            ceilingCellFound = true;
+        }
+        const ladder = toWorkflowDispatchCandidateLadder(definition.cell);
+        const targets = assertCandidateOrder(provider, tier, ladder);
+        const currentCeiling = targets.at(-1);
+        assertTierCeilingsNondecreasing(provider, previousCeiling, currentCeiling, tier);
+        previousCeiling = currentCeiling;
+        for (const [candidateIndex, target] of targets.entries()) {
+            if (!requestedCandidateMatches(provider, requested, target)) {
+                continue;
+            }
+            const candidate = ladder.candidates[candidateIndex];
+            const routeSignature = JSON.stringify(candidateRoute(candidate));
+            if (tierIndex > ceilingIndex) {
+                foundAboveCeiling = true;
+                continue;
+            }
+            if (allowedMatch && allowedMatch.routeSignature !== routeSignature) {
+                throw new Error(`Ambiguous ${provider} candidate ${formatRequestedCandidate(provider, requested)} is configured with multiple routes at or below the ${ceilingTier ?? 'uncapped'} ceiling.`);
+            }
+            allowedMatch ??= {
+                tier,
+                candidate,
+                cellSource: definition.cellSource,
+                routeSignature,
+            };
+        }
+    }
+    if (!ceilingCellFound) {
+        throw new Error(`Exact candidate selection requires a configured ${ceilingTier} candidate ladder for ${provider}.`);
+    }
+    if (!allowedMatch) {
+        const label = formatRequestedCandidate(provider, requested);
+        if (foundAboveCeiling) {
+            throw new Error(`${provider} candidate ${label} is above the configured ${ceilingTier} ceiling.`);
+        }
+        throw new Error(`${provider} candidate ${label} is not present in the configured ${provider} candidate ladders.`);
+    }
+    const resolution = resolveRouteMatrixCell(provider, candidateRoute(allowedMatch.candidate), escalationLevel, allowedMatch.cellSource);
+    if (!resolution || resolution.value === null) {
+        throw new Error(`Configured ${provider} candidate ${formatRequestedCandidate(provider, requested)} cannot compile to an exact dispatch target.`);
+    }
+    return {
+        resolution: {
+            ...resolution,
+            selectionBranch: resolution.selectionBranch === 'escalation-target'
+                ? 'escalation-target'
+                : 'candidate-requested',
+        },
+        candidateTier: allowedMatch.tier,
+    };
+}
 function readProjectDispatchPolicy(provider, content) {
     const frontmatter = getFrontmatterBlock(content);
     if (!frontmatter) {
@@ -613,7 +890,13 @@ function readResolvedConfigCeiling(provider, resolvedConfig) {
     return stripConfigCandidateSource(winner);
 }
 function normalizeRole(value) {
-    return value === 'reviewer' ? 'reviewer' : 'implementer';
+    if (value === undefined) {
+        return 'implementer';
+    }
+    if (value === 'implementer' || value === 'reviewer') {
+        return value;
+    }
+    throw new Error(`Invalid dispatch role ${JSON.stringify(value)}. Expected implementer or reviewer.`);
 }
 function providerValueOrder(provider) {
     if (provider === 'codex') {
@@ -642,6 +925,55 @@ function normalizePreferredValue(provider, value) {
     }
     return normalized;
 }
+function normalizeCeilingTier(value, role) {
+    if (value === undefined) {
+        return null;
+    }
+    const normalized = value.trim();
+    if (!VALID_DISPATCH_MATRIX_TIERS.includes(normalized)) {
+        throw new Error(`Invalid invocation ceiling tier "${normalized}". Valid tiers: ${VALID_DISPATCH_MATRIX_TIERS.join(', ')}.`);
+    }
+    if (role === 'reviewer') {
+        throw new Error('Invocation ceiling tiers are only supported for implementer/fix task dispatch; reviewers use the configured review ceiling.');
+    }
+    return normalized;
+}
+function normalizeRequestedCandidate(provider, role, options) {
+    const model = options.candidateModel?.trim() ?? '';
+    const effort = options.candidateEffort?.trim() ?? '';
+    if (!model && !effort) {
+        return null;
+    }
+    if (options.preferred?.trim()) {
+        throw new Error('Exact candidate flags cannot be combined with --preferred; use one selection path.');
+    }
+    if (role === 'reviewer') {
+        throw new Error('Reviewer candidate requests are not supported; reviewers use the configured review ceiling.');
+    }
+    if (!model) {
+        throw new Error('--candidate-model is required for an exact candidate.');
+    }
+    if (isDirectDispatchRoleName(model)) {
+        throw new Error('Direct dispatch role names are not candidate models; request the configured provider model and effort instead.');
+    }
+    if (provider === 'codex') {
+        if (!effort) {
+            throw new Error('--candidate-effort is required for an exact Codex candidate.');
+        }
+        if (!CODEX_VALUES.includes(effort)) {
+            throw new Error(`Invalid Codex candidate effort "${effort}". Valid values: ${CODEX_VALUES.join(', ')}.`);
+        }
+        return { model, effort };
+    }
+    if (effort) {
+        throw new Error(`--candidate-effort is only valid for Codex; ${provider} candidates use --candidate-model only.`);
+    }
+    if (provider === 'claude' &&
+        !CLAUDE_VALUES.includes(model)) {
+        throw new Error(`Invalid Claude candidate model "${model}". Valid values: ${CLAUDE_VALUES.join(', ')}.`);
+    }
+    return { model };
+}
 function normalizeEscalationLevel(value) {
     if (value === undefined) {
         return 0;
@@ -664,6 +996,10 @@ function selectDispatchValue(provider, role, policy, preferredValue) {
         policy: policy.policy,
         cellSource: policy.cellSource,
         target: policy.target,
+        requestedCandidate: policy.requestedCandidate ?? null,
+        candidateTier: policy.candidateTier ?? null,
+        ceilingTier: policy.ceilingTier ?? policyTier(policy.policy),
+        ceilingTarget: policy.ceilingTarget ?? policy.target,
     };
     if (policy.mode === 'inherit') {
         return {
@@ -677,17 +1013,40 @@ function selectDispatchValue(provider, role, policy, preferredValue) {
             target: null,
         };
     }
+    if (policy.requestedCandidate) {
+        const selectedValue = policy.target
+            ? dispatchValueFromRouteTarget(policy.target)
+            : null;
+        return {
+            ...baseSelection,
+            preferredValue: null,
+            selectedValue,
+            capped: false,
+            selectionMode: selectedValue ? 'candidate' : 'unresolved',
+            selectionBranch: policy.selectionBranch,
+            family: selectionFamily(provider, selectedValue, policy.target),
+            target: policy.target,
+        };
+    }
     if (policy.policy === 'uncapped') {
-        const selectedValue = role === 'reviewer' ? null : preferredValue;
+        const targetValue = policy.target
+            ? dispatchValueFromRouteTarget(policy.target)
+            : null;
+        const selectedValue = role === 'reviewer' ? null : (targetValue ?? preferredValue);
+        const target = role === 'reviewer' || !targetValue ? null : policy.target;
         return {
             ...baseSelection,
             preferredValue: role === 'reviewer' ? null : preferredValue,
             selectedValue,
             capped: false,
             selectionMode: role === 'reviewer' ? 'no-review-target' : 'uncapped',
-            selectionBranch: selectedValue ? 'prompt-persisted' : 'unresolved',
-            family: selectionFamily(provider, selectedValue, null),
-            target: null,
+            selectionBranch: target
+                ? policy.selectionBranch
+                : selectedValue
+                    ? 'prompt-persisted'
+                    : 'unresolved',
+            family: selectionFamily(provider, selectedValue, target),
+            target,
         };
     }
     if (policy.value === null) {
@@ -729,6 +1088,10 @@ function selectDispatchValue(provider, role, policy, preferredValue) {
     }
     const selectedIndex = Math.min(preferredIndex, ceilingIndex);
     const selectedValue = order[selectedIndex];
+    const targetValue = policy.target
+        ? dispatchValueFromRouteTarget(policy.target)
+        : null;
+    const selectedTarget = targetValue === selectedValue ? policy.target : null;
     return {
         ...baseSelection,
         preferredValue,
@@ -736,10 +1099,44 @@ function selectDispatchValue(provider, role, policy, preferredValue) {
         capped: preferredIndex > ceilingIndex,
         selectionMode: 'capped',
         selectionBranch: policy.selectionBranch,
-        family: selectionFamily(provider, selectedValue, selectedValue === policy.value ? policy.target : null),
-        target: selectedValue === policy.value ? policy.target : null,
+        family: selectionFamily(provider, selectedValue, selectedTarget),
+        target: selectedTarget,
     };
 }
+function hasCodexVariantDispatchArgs(dispatchArgs) {
+    return (dispatchArgs !== null &&
+        'variant' in dispatchArgs &&
+        typeof dispatchArgs.variant === 'string' &&
+        dispatchArgs.variant.length > 0);
+}
+function hasModelDispatchArgs(dispatchArgs) {
+    return (dispatchArgs !== null &&
+        'model' in dispatchArgs &&
+        typeof dispatchArgs.model === 'string' &&
+        dispatchArgs.model.length > 0);
+}
+function modelAxis(selection, dispatchArgs) {
+    if (selection.target?.model && dispatchArgs) {
+        return `selected:${selection.target.model}`;
+    }
+    if (hasModelDispatchArgs(dispatchArgs)) {
+        return `selected:${dispatchArgs.model}`;
+    }
+    if (selection.selectionMode === 'inherit-default') {
+        return 'inherited';
+    }
+    return 'unresolved';
+}
+function codexEffortAxis(selection, dispatchArgs) {
+    if (hasCodexVariantDispatchArgs(dispatchArgs) && selection.target?.effort) {
+        return `selected:${selection.target.effort}`;
+    }
+    if (selection.selectionMode === 'inherit-default' ||
+        selection.selectionMode === 'no-review-target') {
+        return 'provider-default';
+    }
+    return 'unresolved';
+}
 /**
  * Join a resolved ceiling value with the active provider's adapter to compute
  * the enforcement mode, mechanism, dispatch args, and verify-on-upgrade flag.
@@ -753,12 +1150,18 @@ function buildProviderResolution(provider, policy, role, orchestratorTier, prefe
             mode: adapter.supportsCeiling ? 'advisory' : 'unsupported',
             mechanism: adapter.mechanism,
             dispatchArgs: null,
+            modelAxis: 'unresolved',
+            effortAxis: provider === 'codex' ? 'provider-default' : 'not-applicable',
             verifyOnDispatch: false,
             cellSource: null,
             target: null,
             selection: {
                 role,
                 preferredValue,
+                requestedCandidate: null,
+                candidateTier: null,
+                ceilingTier: null,
+                ceilingTarget: null,
                 selectedValue: null,
                 capped: false,
                 selectionMode: 'unresolved',
@@ -777,6 +1180,7 @@ function buildProviderResolution(provider, policy, role, orchestratorTier, prefe
     const dispatchArgs = dispatchValue && !isCrossHarness
         ? adapter.compileToDispatchArgs(dispatchValue, role, {
             orchestratorTier,
+            target: selection.target,
         })
         : null;
     let mode;
@@ -794,9 +1198,14 @@ function buildProviderResolution(provider, policy, role, orchestratorTier, prefe
         mode,
         mechanism: adapter.mechanism,
         dispatchArgs,
+        modelAxis: modelAxis(selection, dispatchArgs),
+        effortAxis: provider === 'codex'
+            ? codexEffortAxis(selection, dispatchArgs)
+            : 'not-applicable',
         verifyOnDispatch: dispatchValue && !isCrossHarness
             ? adapter.verifyOnDispatch(dispatchValue, {
                 orchestratorTier,
+                target: selection.target,
             })
             : false,
         cellSource: policy.cellSource,
@@ -851,9 +1260,11 @@ async function resolveDispatchCeiling(context, dependencies, options) {
     const providerDefaultEffort = provider === 'codex'
         ? await resolveCodexProviderDefaultEffort(repoRoot, context, dependencies)
         : 'not-applicable';
+    const requestedCandidate = normalizeRequestedCandidate(provider, role, options);
     const preferredValue = normalizePreferredValue(provider, options.preferred);
+    const ceilingTier = normalizeCeilingTier(options.ceilingTier, role);
     const escalationLevel = normalizeEscalationLevel(options.escalationLevel);
-    const resolvedValue = await resolveCeilingValue(provider, resolvedConfig, projectPath, dependencies, escalationLevel);
+    const resolvedValue = await resolveCeilingValue(provider, resolvedConfig, projectPath, dependencies, escalationLevel, role, preferredValue, requestedCandidate, ceilingTier);
     for (const warning of resolvedValue?.warnings ?? []) {
         context.logger.warn(warning);
     }
@@ -862,6 +1273,32 @@ async function resolveDispatchCeiling(context, dependencies, options) {
         [provider]: providerResolution,
     };
     if (resolvedValue) {
+        const incompleteManagedPreflight = options.preflight === true &&
+            resolvedValue.mode === 'managed' &&
+            providerResolution.mode === 'advisory' &&
+            providerResolution.selection.target?.crossHarness !== true &&
+            providerResolution.selection.selectionMode !== 'no-review-target';
+        if (incompleteManagedPreflight) {
+            const shouldBlock = options.nonInteractive === true ||
+                isNonInteractiveEnv(dependencies.processEnv) ||
+                (!context.interactive && !context.json);
+            const message = shouldBlock ? blockMessage(provider) : undefined;
+            return {
+                status: shouldBlock ? 'blocked' : 'unresolved',
+                provider,
+                value: resolvedValue.value,
+                policyMode: resolvedValue.mode,
+                policy: resolvedValue.policy,
+                source: resolvedValue.source,
+                preset: resolvedValue.preset,
+                unresolved: true,
+                projectPath,
+                providerDefaultEffort,
+                matrix: resolvedValue.matrix,
+                providers,
+                message,
+            };
+        }
         return {
             status: 'resolved',
             provider,
@@ -903,25 +1340,111 @@ async function resolveDispatchCeiling(context, dependencies, options) {
  * Never reads the preset label for dispatch — the preset is surfaced as
  * provenance only.
  */
-async function resolveCeilingValue(provider, resolvedConfig, projectPath, dependencies, escalationLevel) {
+async function resolveCeilingValue(provider, resolvedConfig, projectPath, dependencies, escalationLevel, role, preferredValue, requestedCandidate, invocationCeilingTier) {
     const configCeiling = readResolvedConfigCeiling(provider, resolvedConfig);
     const projectCeiling = await resolveProjectStateCeiling(provider, projectPath, dependencies);
-    const baseCeiling = configCeiling ?? projectCeiling;
+    let baseCeiling = configCeiling ?? projectCeiling;
     if (!baseCeiling) {
         return null;
     }
-    if (baseCeiling.mode === 'inherit' || baseCeiling.policy === 'uncapped') {
+    if (invocationCeilingTier) {
+        baseCeiling = {
+            ...baseCeiling,
+            mode: 'managed',
+            policy: invocationCeilingTier,
+            value: compiledPolicyValueForProvider(provider, compileDispatchPolicyPreset(invocationCeilingTier)),
+            source: 'invocation',
+            preset: invocationCeilingTier,
+            matrix: projectCeiling?.matrix ?? baseCeiling.matrix,
+            cellSource: null,
+            target: null,
+            selectionBranch: 'prompt-persisted',
+            ceilingTier: invocationCeilingTier,
+            ceilingTarget: null,
+        };
+    }
+    if (baseCeiling.mode === 'inherit') {
+        if (requestedCandidate) {
+            throw new Error('Exact candidate selection requires a managed dispatch policy and configured candidate ladder.');
+        }
+        return baseCeiling;
+    }
+    if (requestedCandidate) {
+        if (baseCeiling.policy === 'legacy-ceiling') {
+            throw new Error('Exact candidate selection requires a configured candidate ladder; legacy scalar dispatch ceilings support --preferred only during migration.');
+        }
+        const ceilingTier = policyTier(baseCeiling.policy);
+        const selected = resolveRequestedMatrixCandidate(provider, requestedCandidate, ceilingTier, resolvedConfig, projectCeiling?.matrix ?? null, escalationLevel);
+        const ceilingCell = ceilingTier
+            ? resolveProviderMatrixCell(provider, ceilingTier, resolvedConfig, projectCeiling?.matrix ?? null, escalationLevel)
+            : null;
+        return {
+            ...baseCeiling,
+            value: ceilingCell?.value ?? baseCeiling.value,
+            cellSource: selected.resolution.cellSource,
+            target: selected.resolution.target,
+            selectionBranch: selected.resolution.selectionBranch,
+            warnings: [
+                ...baseCeiling.warnings,
+                ...(ceilingCell?.warnings ?? []),
+                ...selected.resolution.warnings,
+            ],
+            requestedCandidate,
+            candidateTier: selected.candidateTier,
+            ceilingTarget: ceilingCell?.target ?? null,
+            ...(ceilingTier ? { ceilingTier } : {}),
+        };
+    }
+    if (baseCeiling.policy === 'uncapped') {
+        const preferredTier = uncappedPreferredTier(provider, role, preferredValue);
+        if (preferredTier) {
+            const matrixCell = resolveProviderMatrixCell(provider, preferredTier, resolvedConfig, projectCeiling?.matrix ?? null, escalationLevel);
+            if (matrixCell) {
+                return {
+                    ...baseCeiling,
+                    cellSource: matrixCell.cellSource,
+                    target: matrixCell.target,
+                    selectionBranch: matrixCell.selectionBranch,
+                    warnings: [...baseCeiling.warnings, ...matrixCell.warnings],
+                };
+            }
+        }
         return baseCeiling;
     }
     const tier = policyTier(baseCeiling.policy);
     const matrixCell = resolveProviderMatrixCell(provider, tier, resolvedConfig, projectCeiling?.matrix ?? null, escalationLevel);
     if (matrixCell) {
+        if (provider === 'codex' &&
+            role === 'implementer' &&
+            preferredValue !== null &&
+            matrixCell.value !== null) {
+            const order = providerValueOrder(provider);
+            const preferredIndex = order?.indexOf(preferredValue) ?? -1;
+            const ceilingIndex = order?.indexOf(matrixCell.value) ?? -1;
+            if (order && preferredIndex >= 0 && ceilingIndex >= 0) {
+                const selectedValue = order[Math.min(preferredIndex, ceilingIndex)];
+                if (selectedValue !== matrixCell.value) {
+                    const selectedTarget = matrixCell.target?.harness === 'codex'
+                        ? { ...matrixCell.target, effort: selectedValue }
+                        : matrixCell.target;
+                    return {
+                        ...baseCeiling,
+                        value: matrixCell.value,
+                        cellSource: matrixCell.cellSource,
+                        target: selectedTarget,
+                        selectionBranch: matrixCell.selectionBranch,
+                        warnings: [...baseCeiling.warnings, ...matrixCell.warnings],
+                    };
+                }
+            }
+        }
         return {
             ...baseCeiling,
             value: matrixCell.value,
             cellSource: matrixCell.cellSource,
             target: matrixCell.target,
             selectionBranch: matrixCell.selectionBranch,
+            warnings: [...baseCeiling.warnings, ...matrixCell.warnings],
         };
     }
     if (baseCeiling.policy !== 'legacy-ceiling' &&
@@ -950,6 +1473,15 @@ function writeHumanResolution(context, resolution) {
     if (providerResolution) {
         context.logger.info(`Mode: ${providerResolution.mode} (${providerResolution.mechanism})`);
         context.logger.info(`Selection: ${providerResolution.selection.selectionMode}`);
+        if (providerResolution.selection.requestedCandidate) {
+            const requested = providerResolution.selection.requestedCandidate;
+            context.logger.info(`Requested candidate: model=${requested.model}${requested.effort ? ` effort=${requested.effort}` : ''}`);
+            context.logger.info(`Candidate tier: ${providerResolution.selection.candidateTier ?? 'none'}; ceiling tier: ${providerResolution.selection.ceilingTier ?? 'uncapped'}`);
+            const ceilingTarget = providerResolution.selection.ceilingTarget;
+            if (ceilingTarget) {
+                context.logger.info(`Effective ceiling target: model=${ceilingTarget.model ?? 'none'}${ceilingTarget.effort ? ` effort=${ceilingTarget.effort}` : ''}`);
+            }
+        }
         if (providerResolution.target) {
             const details = [
                 `harness=${providerResolution.target.harness}`,
@@ -1023,18 +1555,49 @@ async function runDispatchCeilingResolve(context, dependencies, options) {
         process.exitCode = 1;
     }
 }
+async function runDispatchCeilingChoices(context, options) {
+    const choices = getDispatchPolicyChoices();
+    const format = (options.format ?? 'markdown').trim().toLowerCase();
+    if (context.json || options.json) {
+        context.logger.json({ status: 'ok', choices });
+        process.exitCode = 0;
+        return;
+    }
+    if (format !== 'markdown') {
+        context.logger.error(`Invalid choices format "${options.format}". Valid formats: markdown.`);
+        process.exitCode = 1;
+        return;
+    }
+    context.logger.info(renderDispatchPolicyChoicesMarkdown(choices));
+    process.exitCode = 0;
+}
 export function createProjectDispatchCeilingCommand(overrides = {}) {
     const dependencies = {
         ...DEFAULT_DEPENDENCIES,
         ...overrides,
     };
     const command = new Command('dispatch-ceiling').description('Resolve OAT project dispatch ceiling metadata');
+    command.addCommand(new Command('choices')
+        .description('Print canonical dispatch policy choices')
+        .option('--format <format>', 'Output format: markdown', 'markdown')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (options, cmd) => {
+        const globalOptions = readGlobalOptions(cmd);
+        const context = dependencies.buildCommandContext({
+            ...globalOptions,
+            json: globalOptions.json === true || options.json === true,
+        });
+        await runDispatchCeilingChoices(context, options);
+    }));
     command.addCommand(new Command('resolve')
         .description('Resolve dispatch policy for a provider')
         .requiredOption('--provider <provider>', 'Provider name: codex, claude, or cursor are enforced; unregistered providers resolve as unsupported advisory')
-        .option('--role <role>', 'Dispatch role for variant compilation: implementer (default) or reviewer')
+        .addOption(new Option('--role <role>', 'Dispatch role for variant compilation: implementer (default) or reviewer').choices(['implementer', 'reviewer']))
         .option('--orchestrator-tier <tier>', 'Orchestrator tier, used to flag verify-on-upgrade for above-orchestrator requests')
-        .option('--preferred <value>', 'Preferred implementer/fix dispatch value before applying the resolved policy')
+        .option('--preferred <value>', 'Legacy preferred implementer/fix value before applying the resolved policy')
+        .addOption(new Option('--ceiling-tier <tier>', 'Invocation-only named maximum tier; never persists configuration or project state').choices([...VALID_DISPATCH_MATRIX_TIERS]))
+        .option('--candidate-model <model>', 'Exact configured implementer candidate model beneath the named ceiling')
+        .option('--candidate-effort <effort>', 'Exact configured Codex candidate effort paired with --candidate-model')
         .option('--escalation-level <level>', 'Ordered route entry to select; 0 is the floor and higher values advance through escalation targets')
         .option('--project-path <path>', 'Read project-state policy from an explicit project path')
         .option('--preflight', 'Treat unresolved non-interactive resolution as an implementation block')