@open-agent-toolkit/cli 0.1.46 → 0.1.48

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

@@ -5,13 +5,13 @@ import { getFrontmatterBlock } from '../../shared/frontmatter.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { compileDispatchPolicyPreset, } from '../../../config/dispatch-ceiling-preset.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, validateDispatchRouteTarget, } from '../../../config/oat-config.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,
@@ -85,6 +85,8 @@ function sourceLabel(source) {
             return 'environment';
         case 'project-state':
             return 'project state';
+        case 'invocation':
+            return 'explicit invocation';
         default:
             return 'none';
     }
@@ -151,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;
     }
@@ -173,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) {
@@ -343,6 +369,19 @@ function resolveProviderCellFromValue(provider, providerValue, tier, cellSource,
             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) {
@@ -370,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) {
@@ -645,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') {
@@ -674,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;
@@ -696,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 {
@@ -709,6 +1013,21 @@ 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 targetValue = policy.target
             ? dispatchValueFromRouteTarget(policy.target)
@@ -769,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,
@@ -776,8 +1099,8 @@ 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) {
@@ -835,6 +1158,10 @@ function buildProviderResolution(provider, policy, role, orchestratorTier, prefe
             selection: {
                 role,
                 preferredValue,
+                requestedCandidate: null,
+                candidateTier: null,
+                ceilingTier: null,
+                ceilingTarget: null,
                 selectedValue: null,
                 capped: false,
                 selectionMode: 'unresolved',
@@ -933,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, role, preferredValue);
+    const resolvedValue = await resolveCeilingValue(provider, resolvedConfig, projectPath, dependencies, escalationLevel, role, preferredValue, requestedCandidate, ceilingTier);
     for (const warning of resolvedValue?.warnings ?? []) {
         context.logger.warn(warning);
     }
@@ -944,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,
@@ -985,16 +1340,61 @@ 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, role, preferredValue) {
+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 (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) {
@@ -1014,6 +1414,30 @@ async function resolveCeilingValue(provider, resolvedConfig, projectPath, depend
     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,
@@ -1049,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}`,
@@ -1159,9 +1592,12 @@ export function createProjectDispatchCeilingCommand(overrides = {}) {
     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')

package/dist/commands/providers/codex/materialize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"materialize.d.ts","sourceRoot":"","sources":["../../../../src/commands/providers/codex/materialize.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,sBAAsB,EACtB,qCAAqC,EACtC,MAAM,qCAAqC,CAAC;AAS7C,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAsD5C,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,sBAAsB,GAC7B,MAAM,CAaR;AAwGD,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,qCAAqC,CAAM,GAC7D,OAAO,CAoCT"}
+{"version":3,"file":"materialize.d.ts","sourceRoot":"","sources":["../../../../src/commands/providers/codex/materialize.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,sBAAsB,EACtB,qCAAqC,EACtC,MAAM,qCAAqC,CAAC;AAU7C,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAsD5C,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,sBAAsB,GAC7B,MAAM,CAaR;AA+GD,wBAAgB,6BAA6B,CAC3C,SAAS,GAAE,OAAO,CAAC,qCAAqC,CAAM,GAC7D,OAAO,CAoCT"}

package/dist/commands/providers/codex/materialize.js

@@ -8,6 +8,7 @@ import { ensureDir, fileExists } from '../../../fs/io.js';
 import { resolveProjectRoot, resolveScopeRoot } from '../../../fs/paths.js';
 import { mergeCodexConfigForRole } from '../../../providers/codex/codec/config-merge.js';
 import { materializeCodexRole } from '../../../providers/codex/codec/materialize.js';
+import { withOatManagedCodexRoleOwner } from '../../../providers/codex/codec/shared.js';
 import { Command, Option } from 'commander';
 function createDependencies() {
     return {
@@ -59,12 +60,16 @@ async function buildCodexMaterializePlan(agentName, options, context, dependenci
     const scopeRoot = await dependencies.resolveScopeRoot(scope, context);
     const agentPath = resolveAgentPath(agentName, options, scopeRoot);
     const agent = await dependencies.parseCanonicalAgentFile(agentPath);
-    const role = dependencies.materializeCodexRole({
+    const materializedRole = dependencies.materializeCodexRole({
         agent,
         model,
         effort,
         roleName: options.roleName,
     });
+    const role = {
+        ...materializedRole,
+        content: withOatManagedCodexRoleOwner(materializedRole.content, scope === 'user' ? 'user-config' : 'project-config'),
+    };
     const rolePath = join(scopeRoot, '.codex', role.configFile);
     const configPath = join(scopeRoot, '.codex', 'config.toml');
     return {

package/dist/commands/shared/frontmatter.d.ts

@@ -9,6 +9,10 @@ export declare function isProjectStatePhase(value: string): value is ProjectStat
 export declare function isProjectStateFrontmatterField(value: string): value is ProjectStateFrontmatterField;
 export declare function getFrontmatterBlock(content: string): string | null;
 export declare function getFrontmatterField(frontmatter: string, field: string): string | null;
+export declare function parseFrontmatterScalarFields(frontmatter: string, fields: readonly string[]): {
+    valid: boolean;
+    values: Record<string, string>;
+};
 /**
  * Parse an `oat_generated_at` value into a comparable epoch millisecond time.
  *

package/dist/commands/shared/frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/frontmatter.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,mBAAmB,6CAA8C,CAAC;AAE/E,eAAO,MAAM,oBAAoB,gFAOvB,CAAC;AAEX,eAAO,MAAM,gCAAgC,sgBA2BnC,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AACpE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACtE,MAAM,MAAM,4BAA4B,GACtC,CAAC,OAAO,gCAAgC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,gBAAgB,CAE3E;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB,CAE7E;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,4BAA4B,CAIvC;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGlE;AAED,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CAKf;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxB;AAED,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB"}
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/frontmatter.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,mBAAmB,6CAA8C,CAAC;AAE/E,eAAO,MAAM,oBAAoB,gFAOvB,CAAC;AAEX,eAAO,MAAM,gCAAgC,sgBA2BnC,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AACpE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACtE,MAAM,MAAM,4BAA4B,GACtC,CAAC,OAAO,gCAAgC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,gBAAgB,CAE3E;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB,CAE7E;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,4BAA4B,CAIvC;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGlE;AAED,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CAKf;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CA4BpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxB;AAED,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB"}