@open-agent-toolkit/cli 0.1.46 → 0.1.50

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

@@ -4,14 +4,16 @@ 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 { normalizeDispatchMatrix } from '../../../config/dispatch-matrix.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 { buildDispatchReport, formatDispatchReport, } from '../../../providers/identity/dispatch-report.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 +87,8 @@ function sourceLabel(source) {
             return 'environment';
         case 'project-state':
             return 'project state';
+        case 'invocation':
+            return 'explicit invocation';
         default:
             return 'none';
     }
@@ -123,107 +127,64 @@ function invalidProjectPolicyMessage(value) {
     const actual = typeof value === 'string' ? value : String(value);
     return `Invalid project dispatch policy "${actual}". Valid managed policies: ${validManagedPolicyList()}. Use mode "inherit" for host defaults.`;
 }
-function normalizeProjectMatrixBareValue(provider, value) {
-    if (typeof value !== 'string') {
-        return undefined;
-    }
-    const trimmed = value.trim();
-    if (!trimmed) {
-        return undefined;
-    }
-    const order = providerValueOrder(provider);
-    if (order && !isValidProviderValue(provider, trimmed)) {
-        return undefined;
-    }
-    return trimmed;
-}
-function normalizeProjectMatrixRouteTarget(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        return undefined;
-    }
-    const record = value;
-    const target = {};
-    for (const key of ['harness', 'model', 'effort']) {
-        const rawValue = record[key];
-        if (typeof rawValue === 'string' && rawValue.trim()) {
-            target[key] = rawValue.trim();
-        }
-    }
-    return Object.keys(target).length > 0 ? target : undefined;
+function isProjectMatrixRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
-function normalizeProjectMatrixCell(provider, value) {
-    const bareValue = normalizeProjectMatrixBareValue(provider, value);
-    if (bareValue !== undefined) {
-        return bareValue;
-    }
-    if (!Array.isArray(value) || value.length === 0) {
-        return undefined;
-    }
-    const route = [];
-    for (const entry of value) {
-        const bareEntry = normalizeProjectMatrixBareValue(provider, entry);
-        if (bareEntry !== undefined) {
-            route.push(bareEntry);
+function toProjectMatrixCompatibility(rawMatrix, matrix) {
+    const compatibility = {};
+    for (const [provider, providerValue] of Object.entries(matrix)) {
+        if (typeof providerValue === 'string') {
+            compatibility[provider] = providerValue;
             continue;
         }
-        const target = normalizeProjectMatrixRouteTarget(entry);
-        if (target !== undefined) {
-            route.push(target);
-        }
-    }
-    return route.length > 0 ? route : undefined;
-}
-function normalizeProjectMatrixProviderValue(provider, value) {
-    const bareValue = normalizeProjectMatrixBareValue(provider, value);
-    if (bareValue !== undefined) {
-        return bareValue;
-    }
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        return undefined;
-    }
-    const tierMap = {};
-    for (const [tier, rawCell] of Object.entries(value)) {
-        if (!VALID_DISPATCH_MATRIX_TIERS.includes(tier)) {
-            continue;
-        }
-        const normalized = normalizeProjectMatrixCell(provider, rawCell);
-        if (normalized !== undefined) {
-            tierMap[tier] = normalized;
+        const rawProvider = isProjectMatrixRecord(rawMatrix[provider])
+            ? rawMatrix[provider]
+            : {};
+        const tiers = {};
+        for (const [tier, cell] of Object.entries(providerValue)) {
+            const matrixTier = tier;
+            const rawCell = rawProvider[matrixTier];
+            const ladder = toWorkflowDispatchCandidateLadder(cell);
+            const firstCandidate = ladder.candidates[0];
+            if (typeof rawCell === 'string' && typeof firstCandidate === 'string') {
+                tiers[matrixTier] = firstCandidate;
+                continue;
+            }
+            if (Array.isArray(rawCell) &&
+                firstCandidate !== undefined &&
+                isWorkflowDispatchFallbackRoute(firstCandidate)) {
+                tiers[matrixTier] = firstCandidate.route;
+                continue;
+            }
+            tiers[matrixTier] = cell;
         }
+        compatibility[provider] = tiers;
     }
-    return Object.keys(tierMap).length > 0 ? tierMap : undefined;
+    return compatibility;
 }
 function readProjectDispatchMatrix(value) {
     if (value === undefined || value === null) {
-        return { matrix: null, warnings: [] };
-    }
-    if (typeof value !== 'object' || Array.isArray(value)) {
-        return {
-            matrix: null,
-            warnings: [
-                'Ignoring malformed oat_dispatch_policy.matrix in project state.',
-            ],
-        };
-    }
-    const matrix = {};
-    for (const [provider, rawProviderValue] of Object.entries(value)) {
-        if (!provider.trim()) {
-            continue;
-        }
-        const normalized = normalizeProjectMatrixProviderValue(provider, rawProviderValue);
-        if (normalized !== undefined) {
-            matrix[provider] = normalized;
-        }
-    }
-    if (Object.keys(matrix).length === 0) {
+        return { matrix: null, compatibilityMatrix: null, warnings: [] };
+    }
+    const normalized = normalizeDispatchMatrix(value, {
+        pathPrefix: 'oat_dispatch_policy.matrix',
+        compatibilityMode: 'project-state',
+    });
+    const matrix = Object.fromEntries(Object.entries(normalized.providers).filter(([provider]) => Boolean(provider.trim())));
+    if (!isProjectMatrixRecord(value) || Object.keys(matrix).length === 0) {
         return {
             matrix: null,
+            compatibilityMatrix: null,
             warnings: [
                 'Ignoring malformed oat_dispatch_policy.matrix in project state.',
             ],
         };
     }
-    return { matrix, warnings: [] };
+    return {
+        matrix,
+        compatibilityMatrix: toProjectMatrixCompatibility(value, matrix),
+        warnings: [],
+    };
 }
 function policyTier(policy) {
     return typeof policy === 'string' &&
@@ -343,6 +304,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 +344,214 @@ 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,
+                candidateIndex,
+                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,
+        candidateIndex: allowedMatch.candidateIndex,
+    };
+}
 function readProjectDispatchPolicy(provider, content) {
     const frontmatter = getFrontmatterBlock(content);
     if (!frontmatter) {
@@ -394,9 +576,11 @@ function readProjectDispatchPolicy(provider, content) {
             source: 'project-state',
             preset: null,
             matrix: parsedMatrix.matrix,
+            matrixCompatibility: parsedMatrix.compatibilityMatrix,
             cellSource: null,
             target: null,
             selectionBranch: 'inherit',
+            candidateIndex: null,
             warnings: parsedMatrix.warnings,
         };
     }
@@ -417,9 +601,11 @@ function readProjectDispatchPolicy(provider, content) {
             source: 'project-state',
             preset: policyValue,
             matrix: parsedMatrix.matrix,
+            matrixCompatibility: parsedMatrix.compatibilityMatrix,
             cellSource: null,
             target: null,
             selectionBranch: 'prompt-persisted',
+            candidateIndex: null,
             warnings: parsedMatrix.warnings,
         };
     }
@@ -444,9 +630,11 @@ function readProjectDispatchPolicy(provider, content) {
         source: 'project-state',
         preset: policyValue,
         matrix: parsedMatrix.matrix,
+        matrixCompatibility: parsedMatrix.compatibilityMatrix,
         cellSource: 'project-state',
         target: null,
         selectionBranch: 'prompt-persisted',
+        candidateIndex: null,
         warnings: parsedMatrix.warnings,
     };
 }
@@ -477,6 +665,7 @@ function readLegacyProjectDispatchCeiling(provider, parsed) {
         cellSource: 'project-state',
         target: null,
         selectionBranch: 'prompt-persisted',
+        candidateIndex: null,
         warnings: [],
     };
 }
@@ -545,9 +734,11 @@ function stripConfigCandidateSource(candidate) {
         source: candidate.source,
         preset: candidate.preset,
         matrix: candidate.matrix,
+        matrixCompatibility: candidate.matrixCompatibility,
         cellSource: candidate.cellSource,
         target: candidate.target,
         selectionBranch: candidate.selectionBranch,
+        candidateIndex: candidate.candidateIndex,
         warnings: candidate.warnings,
     };
 }
@@ -570,6 +761,7 @@ function readResolvedConfigPolicyCandidate(provider, resolvedConfig) {
             cellSource: null,
             target: null,
             selectionBranch: 'inherit',
+            candidateIndex: null,
             warnings: [],
             configSource: modeEntry.source,
         };
@@ -595,6 +787,7 @@ function readResolvedConfigPolicyCandidate(provider, resolvedConfig) {
             cellSource: null,
             target: null,
             selectionBranch: 'prompt-persisted',
+            candidateIndex: null,
             warnings: [],
             configSource,
         };
@@ -625,6 +818,7 @@ function readResolvedLegacyConfigCeilingCandidate(provider, resolvedConfig) {
         cellSource: source,
         target: null,
         selectionBranch: 'prompt-persisted',
+        candidateIndex: null,
         warnings: [],
         configSource: entry.source,
     };
@@ -645,7 +839,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 +874,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 +945,11 @@ function selectDispatchValue(provider, role, policy, preferredValue) {
         policy: policy.policy,
         cellSource: policy.cellSource,
         target: policy.target,
+        requestedCandidate: policy.requestedCandidate ?? null,
+        candidateTier: policy.candidateTier ?? null,
+        candidateIndex: policy.candidateIndex,
+        ceilingTier: policy.ceilingTier ?? policyTier(policy.policy),
+        ceilingTarget: policy.ceilingTarget ?? policy.target,
     };
     if (policy.mode === 'inherit') {
         return {
@@ -709,6 +963,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 +1038,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 +1049,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 +1108,11 @@ function buildProviderResolution(provider, policy, role, orchestratorTier, prefe
             selection: {
                 role,
                 preferredValue,
+                requestedCandidate: null,
+                candidateTier: null,
+                candidateIndex: null,
+                ceilingTier: null,
+                ceilingTarget: null,
                 selectedValue: null,
                 capped: false,
                 selectionMode: 'unresolved',
@@ -933,9 +1211,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 +1224,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.matrixCompatibility ?? resolvedValue.matrix,
+                providers,
+                message,
+            };
+        }
         return {
             status: 'resolved',
             provider,
@@ -955,7 +1261,7 @@ async function resolveDispatchCeiling(context, dependencies, options) {
             unresolved: false,
             projectPath,
             providerDefaultEffort,
-            matrix: resolvedValue.matrix,
+            matrix: resolvedValue.matrixCompatibility ?? resolvedValue.matrix,
             providers,
         };
     }
@@ -985,16 +1291,63 @@ 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,
+            matrixCompatibility: projectCeiling?.matrixCompatibility ?? baseCeiling.matrixCompatibility,
+            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,
+            candidateIndex: selected.candidateIndex,
+            ceilingTarget: ceilingCell?.target ?? null,
+            ...(ceilingTier ? { ceilingTier } : {}),
+        };
+    }
     if (baseCeiling.policy === 'uncapped') {
         const preferredTier = uncappedPreferredTier(provider, role, preferredValue);
         if (preferredTier) {
@@ -1014,6 +1367,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 +1426,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}`,
@@ -1100,14 +1486,91 @@ function writeHumanResolution(context, resolution) {
         }
     }
 }
+function reportRole(action) {
+    if (action === 'review') {
+        return 'reviewer';
+    }
+    return action === 'fix' ? 'fix' : 'implementer';
+}
+function reportControl(axis, dispatchArgs, reason) {
+    if (axis.startsWith('selected:')) {
+        return {
+            value: axis.slice('selected:'.length),
+            mechanism: dispatchArgs && 'variant' in dispatchArgs
+                ? 'materialized-role'
+                : 'task-model-argument',
+            reason,
+        };
+    }
+    if (axis === 'inherited') {
+        return { value: null, mechanism: 'host-inherited', reason };
+    }
+    if (axis === 'provider-default') {
+        return { value: null, mechanism: 'provider-default', reason };
+    }
+    if (axis === 'not-applicable') {
+        return { value: null, mechanism: 'not-applicable', reason };
+    }
+    return { value: null, mechanism: 'base-role', reason };
+}
+function buildResolutionReport(resolution, options) {
+    const hasScope = options.reportScope !== undefined;
+    const hasAction = options.reportAction !== undefined;
+    if (!hasScope && !hasAction) {
+        return null;
+    }
+    if (!hasScope || !hasAction) {
+        throw new Error('--report-scope and --report-action must be provided together.');
+    }
+    const scope = options.reportScope.trim();
+    if (!scope) {
+        throw new Error('--report-scope must be a non-empty value.');
+    }
+    const action = options.reportAction;
+    const role = reportRole(action);
+    const providerResolution = resolution.providers[resolution.provider];
+    if (!providerResolution) {
+        throw new Error(`Dispatch report resolution is missing provider data for "${resolution.provider}".`);
+    }
+    const expectedResolverRole = role === 'reviewer' ? 'reviewer' : 'implementer';
+    if (providerResolution.selection.role !== expectedResolverRole) {
+        throw new Error(`Invalid dispatch report action/role context: ${action}/${role} requires resolver role ${expectedResolverRole}, received ${providerResolution.selection.role}.`);
+    }
+    return buildDispatchReport({
+        scope,
+        action,
+        role,
+        resolution,
+        requestedControls: {
+            model: reportControl(providerResolution.modelAxis, providerResolution.dispatchArgs, 'Derived from the completed resolver model-axis result.'),
+            effort: reportControl(providerResolution.effortAxis, providerResolution.dispatchArgs, 'Derived from the completed resolver effort-axis result.'),
+        },
+        configuredDefaults: {
+            model: null,
+            modelSource: null,
+            effort: resolution.provider === 'codex' &&
+                resolution.providerDefaultEffort !== 'unknown'
+                ? resolution.providerDefaultEffort
+                : null,
+            effortSource: resolution.provider === 'codex' &&
+                resolution.providerDefaultEffort !== 'unknown'
+                ? 'codex-config'
+                : null,
+        },
+    });
+}
 async function runDispatchCeilingResolve(context, dependencies, options) {
     try {
         const resolution = await resolveDispatchCeiling(context, dependencies, options);
+        const dispatchReport = buildResolutionReport(resolution, options);
         if (context.json) {
-            context.logger.json(resolution);
+            context.logger.json(dispatchReport ? { ...resolution, dispatchReport } : resolution);
         }
         else {
             writeHumanResolution(context, resolution);
+            if (dispatchReport) {
+                context.logger.info(formatDispatchReport(dispatchReport));
+            }
         }
         process.exitCode = resolution.status === 'blocked' ? 1 : 0;
     }
@@ -1159,13 +1622,18 @@ 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')
         .option('--non-interactive', 'Force non-interactive block behavior when the ceiling is unresolved')
+        .option('--report-scope <scope>', 'Include Dispatch Report V1 for the explicit workflow scope')
+        .addOption(new Option('--report-action <action>', 'Dispatch Report V1 action; must match the resolver role').choices(['implementation', 'fix', 'review']))
         .option('--json', 'Output machine-readable JSON')
         .action(async (options, cmd) => {
         const globalOptions = readGlobalOptions(cmd);