@open-agent-toolkit/cli 0.1.42 → 0.1.45

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

@@ -3,23 +3,20 @@ import { isAbsolute, join } from 'node:path';
 import { buildCommandContext, } from '../../../app/command-context.js';
 import { getFrontmatterBlock } from '../../shared/frontmatter.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
-import { resolveActiveProject, } from '../../../config/oat-config.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 { resolveEffectiveConfig, } from '../../../config/resolve.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
 import TOML from '@iarna/toml';
 import { getCeilingAdapter, } from '../../../providers/ceiling/registry.js';
+import { classifyModelFamily, } from '../../../providers/identity/family.js';
 import { Command } from 'commander';
 import YAML from 'yaml';
 const CODEX_VALUES = [
-    'low',
-    'medium',
-    'high',
-    'xhigh',
+    ...VALID_CODEX_DISPATCH_CEILINGS,
 ];
 const CLAUDE_VALUES = [
-    'haiku',
-    'sonnet',
-    'opus',
+    ...VALID_CLAUDE_DISPATCH_CEILINGS,
 ];
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
@@ -58,7 +55,7 @@ function isValidProviderValue(provider, value) {
         return (typeof value === 'string' &&
             CLAUDE_VALUES.includes(value));
     }
-    return false;
+    return typeof value === 'string' && value.trim().length > 0;
 }
 function configSourceToCeilingSource(source) {
     if (source === 'local') {
@@ -104,7 +101,244 @@ function providerLabel(provider) {
 function resolveTargetProjectPath(repoRoot, projectPath) {
     return isAbsolute(projectPath) ? projectPath : join(repoRoot, projectPath);
 }
-function readProjectDispatchCeiling(provider, content) {
+function isValidManagedPolicy(value) {
+    return (typeof value === 'string' &&
+        VALID_MANAGED_DISPATCH_POLICIES.includes(value));
+}
+function validManagedPolicyList() {
+    return VALID_MANAGED_DISPATCH_POLICIES.join(', ');
+}
+function validProviderValueList(provider) {
+    return providerValueOrder(provider)?.join(', ') ?? 'none';
+}
+function compiledPolicyValueForProvider(provider, compiled) {
+    if (!('providers' in compiled)) {
+        return null;
+    }
+    const value = compiled.providers[provider];
+    return isValidProviderValue(provider, value) ? value : null;
+}
+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 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);
+            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;
+        }
+    }
+    return Object.keys(tierMap).length > 0 ? tierMap : undefined;
+}
+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,
+            warnings: [
+                'Ignoring malformed oat_dispatch_policy.matrix in project state.',
+            ],
+        };
+    }
+    return { matrix, warnings: [] };
+}
+function policyTier(policy) {
+    return typeof policy === 'string' &&
+        VALID_DISPATCH_MATRIX_TIERS.includes(policy)
+        ? policy
+        : null;
+}
+function dispatchValueFromRouteTarget(target) {
+    const adapter = getCeilingAdapter(target.harness);
+    if (adapter.mechanism === 'pinned-variant') {
+        return target.effort ?? null;
+    }
+    if (adapter.mechanism === 'model-arg') {
+        return target.model ?? null;
+    }
+    return null;
+}
+function routeTargetFromBareValue(provider, value, routeIndex, routeLength) {
+    const adapter = getCeilingAdapter(provider);
+    const target = {
+        harness: provider,
+        crossHarness: false,
+        routeIndex,
+        routeLength,
+    };
+    if (adapter.mechanism === 'pinned-variant') {
+        target.effort = value;
+    }
+    else {
+        target.model = value;
+    }
+    return target;
+}
+function routeTargetFromObject(provider, target, routeIndex, routeLength) {
+    const harness = target.harness ?? provider;
+    return {
+        harness,
+        ...(target.model ? { model: target.model } : {}),
+        ...(target.effort ? { effort: target.effort } : {}),
+        crossHarness: harness !== provider,
+        routeIndex,
+        routeLength,
+    };
+}
+function resolveRouteMatrixCell(provider, route, escalationLevel, cellSource) {
+    const routeIndex = Math.min(escalationLevel, route.length - 1);
+    const entry = route[routeIndex];
+    if (entry === undefined) {
+        return null;
+    }
+    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);
+    return {
+        value,
+        cellSource,
+        target,
+        selectionBranch: routeIndex > 0 ? 'escalation-target' : 'matrix-pinned',
+    };
+}
+function resolveProviderCellFromValue(provider, providerValue, tier, cellSource, escalationLevel) {
+    if (providerValue === undefined) {
+        return null;
+    }
+    if (typeof providerValue === 'string') {
+        return {
+            value: providerValue,
+            cellSource,
+            target: null,
+            selectionBranch: 'prompt-persisted',
+        };
+    }
+    if (tier === null) {
+        return null;
+    }
+    const cell = providerValue[tier];
+    if (cell === undefined) {
+        return null;
+    }
+    if (typeof cell === 'string') {
+        return {
+            value: cell,
+            cellSource,
+            target: null,
+            selectionBranch: 'matrix-pinned',
+        };
+    }
+    return resolveRouteMatrixCell(provider, cell, escalationLevel, cellSource);
+}
+function resolveProviderMatrixCell(provider, tier, resolvedConfig, projectMatrix, escalationLevel) {
+    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 resolved = resolveProviderCellFromValue(provider, layer.providers?.[provider], tier, layer.source, escalationLevel);
+        if (resolved) {
+            selected = resolved;
+        }
+    }
+    return selected;
+}
+function readProjectDispatchPolicy(provider, content) {
     const frontmatter = getFrontmatterBlock(content);
     if (!frontmatter) {
         return null;
@@ -113,6 +347,78 @@ function readProjectDispatchCeiling(provider, content) {
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
         return null;
     }
+    const policy = parsed['oat_dispatch_policy'];
+    if (!policy || typeof policy !== 'object' || Array.isArray(policy)) {
+        return null;
+    }
+    const policyRecord = policy;
+    const parsedMatrix = readProjectDispatchMatrix(policyRecord['matrix']);
+    const mode = policyRecord['mode'];
+    if (mode === 'inherit') {
+        return {
+            mode,
+            policy: null,
+            value: null,
+            source: 'project-state',
+            preset: null,
+            matrix: parsedMatrix.matrix,
+            cellSource: null,
+            target: null,
+            selectionBranch: 'inherit',
+            warnings: parsedMatrix.warnings,
+        };
+    }
+    if (mode !== 'managed') {
+        const actual = typeof mode === 'string' ? mode : String(mode);
+        throw new Error(`Invalid project dispatch policy mode "${actual}". Valid modes: managed, inherit.`);
+    }
+    const policyValue = policyRecord['policy'];
+    if (!isValidManagedPolicy(policyValue)) {
+        throw new Error(invalidProjectPolicyMessage(policyValue));
+    }
+    const compiled = compileDispatchPolicyPreset(policyValue);
+    if (policyValue === 'uncapped') {
+        return {
+            mode,
+            policy: policyValue,
+            value: null,
+            source: 'project-state',
+            preset: policyValue,
+            matrix: parsedMatrix.matrix,
+            cellSource: null,
+            target: null,
+            selectionBranch: 'prompt-persisted',
+            warnings: parsedMatrix.warnings,
+        };
+    }
+    const providers = policyRecord['providers'];
+    const explicitValue = providers && typeof providers === 'object' && !Array.isArray(providers)
+        ? providers[provider]
+        : null;
+    const providerOrder = providerValueOrder(provider);
+    if (providerOrder &&
+        explicitValue !== null &&
+        explicitValue !== undefined &&
+        !isValidProviderValue(provider, explicitValue)) {
+        throw new Error(`Invalid project dispatch policy provider value "${String(explicitValue)}" for ${provider}. Valid values: ${validProviderValueList(provider)}.`);
+    }
+    const value = isValidProviderValue(provider, explicitValue)
+        ? explicitValue
+        : compiledPolicyValueForProvider(provider, compiled);
+    return {
+        mode,
+        policy: policyValue,
+        value,
+        source: 'project-state',
+        preset: policyValue,
+        matrix: parsedMatrix.matrix,
+        cellSource: 'project-state',
+        target: null,
+        selectionBranch: 'prompt-persisted',
+        warnings: parsedMatrix.warnings,
+    };
+}
+function readLegacyProjectDispatchCeiling(provider, parsed) {
     const ceiling = parsed['oat_dispatch_ceiling'];
     if (!ceiling || typeof ceiling !== 'object' || Array.isArray(ceiling)) {
         return null;
@@ -130,21 +436,42 @@ function readProjectDispatchCeiling(provider, content) {
     }
     const presetValue = ceilingRecord['preset'];
     return {
+        mode: 'managed',
+        policy: 'legacy-ceiling',
         value,
+        source: 'project-state',
         preset: typeof presetValue === 'string' ? presetValue : null,
+        matrix: null,
+        cellSource: 'project-state',
+        target: null,
+        selectionBranch: 'prompt-persisted',
+        warnings: [],
     };
 }
+function readProjectDispatchCeiling(provider, content) {
+    const frontmatter = getFrontmatterBlock(content);
+    if (!frontmatter) {
+        return null;
+    }
+    const parsed = YAML.parse(frontmatter);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return null;
+    }
+    return (readProjectDispatchPolicy(provider, content) ??
+        readLegacyProjectDispatchCeiling(provider, parsed));
+}
 async function resolveProjectStateCeiling(provider, projectPath, dependencies) {
     if (!projectPath) {
         return null;
     }
+    let content;
     try {
-        const content = await dependencies.readFile(join(projectPath, 'state.md'));
-        return readProjectDispatchCeiling(provider, content);
+        content = await dependencies.readFile(join(projectPath, 'state.md'));
     }
     catch {
         return null;
     }
+    return readProjectDispatchCeiling(provider, content);
 }
 async function resolveProjectPath(repoRoot, dependencies, options) {
     if (options.projectPath) {
@@ -156,20 +483,135 @@ async function resolveProjectPath(repoRoot, dependencies, options) {
     }
     return join(repoRoot, activeProject.path);
 }
-function readResolvedConfigCeiling(provider, resolvedConfig) {
+function isConfigCandidateSource(source) {
+    return source !== undefined && source !== 'default';
+}
+function configSourcePrecedence(source) {
+    switch (source) {
+        case 'env':
+            return 4;
+        case 'local':
+            return 3;
+        case 'shared':
+            return 2;
+        case 'user':
+            return 1;
+        case 'default':
+            return 0;
+    }
+}
+function lowerPrecedenceConfigSource(left, right) {
+    return configSourcePrecedence(left) <= configSourcePrecedence(right)
+        ? left
+        : right;
+}
+function stripConfigCandidateSource(candidate) {
+    return {
+        mode: candidate.mode,
+        policy: candidate.policy,
+        value: candidate.value,
+        source: candidate.source,
+        preset: candidate.preset,
+        matrix: candidate.matrix,
+        cellSource: candidate.cellSource,
+        target: candidate.target,
+        selectionBranch: candidate.selectionBranch,
+        warnings: candidate.warnings,
+    };
+}
+function readResolvedConfigPolicyCandidate(provider, resolvedConfig) {
+    const modeEntry = resolvedConfig.resolved['workflow.dispatchPolicy.mode'];
+    const policyEntry = resolvedConfig.resolved['workflow.dispatchPolicy.policy'];
+    if (modeEntry?.value === 'inherit' &&
+        isConfigCandidateSource(modeEntry.source)) {
+        const source = configSourceToCeilingSource(modeEntry.source);
+        if (source === null) {
+            return null;
+        }
+        return {
+            mode: 'inherit',
+            policy: null,
+            value: null,
+            source,
+            preset: null,
+            matrix: null,
+            cellSource: null,
+            target: null,
+            selectionBranch: 'inherit',
+            warnings: [],
+            configSource: modeEntry.source,
+        };
+    }
+    if (modeEntry?.value === 'managed' &&
+        isValidManagedPolicy(policyEntry?.value) &&
+        isConfigCandidateSource(modeEntry.source) &&
+        isConfigCandidateSource(policyEntry?.source)) {
+        const policy = policyEntry.value;
+        const compiled = compileDispatchPolicyPreset(policy);
+        const configSource = lowerPrecedenceConfigSource(modeEntry.source, policyEntry.source);
+        const source = configSourceToCeilingSource(configSource);
+        if (source === null) {
+            return null;
+        }
+        return {
+            mode: 'managed',
+            policy,
+            value: compiledPolicyValueForProvider(provider, compiled),
+            source,
+            preset: policy,
+            matrix: null,
+            cellSource: null,
+            target: null,
+            selectionBranch: 'prompt-persisted',
+            warnings: [],
+            configSource,
+        };
+    }
+    return null;
+}
+function readResolvedLegacyConfigCeilingCandidate(provider, resolvedConfig) {
     // Read the concrete per-provider value from the nested key. The flat
     // `workflow.dispatchCeiling.<provider>` shape was removed in p01; never read
     // the preset label for dispatch.
     const entry = resolvedConfig.resolved[`workflow.dispatchCeiling.providers.${provider}`];
-    const source = entry ? configSourceToCeilingSource(entry.source) : null;
-    if (!entry || !source || !isValidProviderValue(provider, entry.value)) {
+    if (!entry ||
+        !isConfigCandidateSource(entry.source) ||
+        !isValidProviderValue(provider, entry.value)) {
+        return null;
+    }
+    const source = configSourceToCeilingSource(entry.source);
+    if (source === null) {
         return null;
     }
     return {
+        mode: 'managed',
+        policy: 'legacy-ceiling',
         value: entry.value,
         source,
+        preset: null,
+        matrix: null,
+        cellSource: source,
+        target: null,
+        selectionBranch: 'prompt-persisted',
+        warnings: [],
+        configSource: entry.source,
     };
 }
+function readResolvedConfigCeiling(provider, resolvedConfig) {
+    const policyCandidate = readResolvedConfigPolicyCandidate(provider, resolvedConfig);
+    const legacyCandidate = readResolvedLegacyConfigCeilingCandidate(provider, resolvedConfig);
+    if (!policyCandidate) {
+        return legacyCandidate ? stripConfigCandidateSource(legacyCandidate) : null;
+    }
+    if (!legacyCandidate) {
+        return stripConfigCandidateSource(policyCandidate);
+    }
+    const winner = configSourcePrecedence(policyCandidate.configSource) >=
+        configSourcePrecedence(legacyCandidate.configSource)
+        ? policyCandidate
+        : legacyCandidate;
+    return stripConfigCandidateSource(winner);
+}
 function normalizeRole(value) {
     return value === 'reviewer' ? 'reviewer' : 'implementer';
 }
@@ -200,32 +642,102 @@ function normalizePreferredValue(provider, value) {
     }
     return normalized;
 }
-function selectDispatchValue(provider, role, ceilingValue, preferredValue) {
+function normalizeEscalationLevel(value) {
+    if (value === undefined) {
+        return 0;
+    }
+    const normalized = value.trim();
+    if (!/^\d+$/.test(normalized)) {
+        throw new Error(`Invalid escalation level "${value}". Use a non-negative integer.`);
+    }
+    return Number.parseInt(normalized, 10);
+}
+function selectionFamily(provider, value, target) {
+    return value
+        ? classifyModelFamily({ value, providerId: target?.harness ?? provider })
+        : 'unknown';
+}
+function selectDispatchValue(provider, role, policy, preferredValue) {
+    const baseSelection = {
+        role,
+        policyMode: policy.mode,
+        policy: policy.policy,
+        cellSource: policy.cellSource,
+        target: policy.target,
+    };
+    if (policy.mode === 'inherit') {
+        return {
+            ...baseSelection,
+            preferredValue: null,
+            selectedValue: null,
+            capped: false,
+            selectionMode: 'inherit-default',
+            selectionBranch: 'inherit',
+            family: 'unknown',
+            target: null,
+        };
+    }
+    if (policy.policy === 'uncapped') {
+        const selectedValue = role === 'reviewer' ? null : preferredValue;
+        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,
+        };
+    }
+    if (policy.value === null) {
+        return {
+            ...baseSelection,
+            preferredValue: null,
+            selectedValue: null,
+            capped: false,
+            selectionMode: policy.target ? 'unresolved' : 'capped',
+            selectionBranch: policy.selectionBranch,
+            family: 'unknown',
+            target: policy.target,
+        };
+    }
     if (role === 'reviewer' || preferredValue === null) {
         return {
-            role,
+            ...baseSelection,
             preferredValue,
-            selectedValue: ceilingValue,
+            selectedValue: policy.value,
             capped: false,
+            selectionMode: role === 'reviewer' ? 'review-target' : 'capped',
+            selectionBranch: policy.selectionBranch,
+            family: selectionFamily(provider, policy.value, policy.target),
         };
     }
     const order = providerValueOrder(provider);
     const preferredIndex = order?.indexOf(preferredValue) ?? -1;
-    const ceilingIndex = order?.indexOf(ceilingValue) ?? -1;
+    const ceilingIndex = order?.indexOf(policy.value) ?? -1;
     if (!order || preferredIndex < 0 || ceilingIndex < 0) {
         return {
-            role,
+            ...baseSelection,
             preferredValue,
-            selectedValue: ceilingValue,
+            selectedValue: policy.value,
             capped: false,
+            selectionMode: 'capped',
+            selectionBranch: policy.selectionBranch,
+            family: selectionFamily(provider, policy.value, policy.target),
         };
     }
     const selectedIndex = Math.min(preferredIndex, ceilingIndex);
+    const selectedValue = order[selectedIndex];
     return {
-        role,
+        ...baseSelection,
         preferredValue,
-        selectedValue: order[selectedIndex],
+        selectedValue,
         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,
     };
 }
 /**
@@ -233,28 +745,40 @@ function selectDispatchValue(provider, role, ceilingValue, preferredValue) {
  * the enforcement mode, mechanism, dispatch args, and verify-on-upgrade flag.
  * Mode is computed here at call time — it is never read from persisted state.
  */
-function buildProviderResolution(provider, value, role, orchestratorTier, preferredValue) {
+function buildProviderResolution(provider, policy, role, orchestratorTier, preferredValue) {
     const adapter = getCeilingAdapter(provider);
-    if (value === null) {
+    if (policy === null) {
         return {
             value: null,
             mode: adapter.supportsCeiling ? 'advisory' : 'unsupported',
             mechanism: adapter.mechanism,
             dispatchArgs: null,
             verifyOnDispatch: false,
+            cellSource: null,
+            target: null,
             selection: {
                 role,
                 preferredValue,
                 selectedValue: null,
                 capped: false,
+                selectionMode: 'unresolved',
+                selectionBranch: 'unresolved',
+                family: 'unknown',
+                target: null,
+                cellSource: null,
+                policyMode: null,
+                policy: null,
             },
         };
     }
-    const selection = selectDispatchValue(provider, role, value, preferredValue);
-    const dispatchValue = selection.selectedValue ?? value;
-    const dispatchArgs = adapter.compileToDispatchArgs(dispatchValue, role, {
-        orchestratorTier,
-    });
+    const selection = selectDispatchValue(provider, role, policy, preferredValue);
+    const dispatchValue = selection.selectedValue;
+    const isCrossHarness = selection.target?.crossHarness === true;
+    const dispatchArgs = dispatchValue && !isCrossHarness
+        ? adapter.compileToDispatchArgs(dispatchValue, role, {
+            orchestratorTier,
+        })
+        : null;
     let mode;
     if (!adapter.supportsCeiling) {
         mode = 'unsupported';
@@ -266,13 +790,17 @@ function buildProviderResolution(provider, value, role, orchestratorTier, prefer
         mode = 'advisory';
     }
     return {
-        value,
+        value: policy.value,
         mode,
         mechanism: adapter.mechanism,
         dispatchArgs,
-        verifyOnDispatch: adapter.verifyOnDispatch(dispatchValue, {
-            orchestratorTier,
-        }),
+        verifyOnDispatch: dispatchValue && !isCrossHarness
+            ? adapter.verifyOnDispatch(dispatchValue, {
+                orchestratorTier,
+            })
+            : false,
+        cellSource: policy.cellSource,
+        target: selection.target,
         selection,
     };
 }
@@ -305,7 +833,7 @@ async function resolveCodexProviderDefaultEffort(repoRoot, context, dependencies
 }
 function blockMessage(provider) {
     const label = providerLabel(provider);
-    return `BLOCKED: ${label} dispatch ceiling is unresolved in non-interactive mode.\nSet workflow.dispatchCeiling.providers.${provider} in .oat/config.json or oat_dispatch_ceiling in project state.`;
+    return `BLOCKED: ${label} dispatch policy is unresolved in non-interactive mode.\nSet workflow.dispatchPolicy.mode/workflow.dispatchPolicy.policy, workflow.dispatchCeiling.providers.${provider}, oat_dispatch_policy, or legacy oat_dispatch_ceiling.`;
 }
 function isNonInteractiveEnv(env) {
     return env['OAT_NON_INTERACTIVE'] === '1';
@@ -324,8 +852,12 @@ async function resolveDispatchCeiling(context, dependencies, options) {
         ? await resolveCodexProviderDefaultEffort(repoRoot, context, dependencies)
         : 'not-applicable';
     const preferredValue = normalizePreferredValue(provider, options.preferred);
-    const resolvedValue = await resolveCeilingValue(provider, resolvedConfig, projectPath, dependencies);
-    const providerResolution = buildProviderResolution(provider, resolvedValue?.value ?? null, role, orchestratorTier, preferredValue);
+    const escalationLevel = normalizeEscalationLevel(options.escalationLevel);
+    const resolvedValue = await resolveCeilingValue(provider, resolvedConfig, projectPath, dependencies, escalationLevel);
+    for (const warning of resolvedValue?.warnings ?? []) {
+        context.logger.warn(warning);
+    }
+    const providerResolution = buildProviderResolution(provider, resolvedValue, role, orchestratorTier, preferredValue);
     const providers = {
         [provider]: providerResolution,
     };
@@ -334,11 +866,14 @@ async function resolveDispatchCeiling(context, dependencies, options) {
             status: 'resolved',
             provider,
             value: resolvedValue.value,
+            policyMode: resolvedValue.mode,
+            policy: resolvedValue.policy,
             source: resolvedValue.source,
             preset: resolvedValue.preset,
             unresolved: false,
             projectPath,
             providerDefaultEffort,
+            matrix: resolvedValue.matrix,
             providers,
         };
     }
@@ -350,11 +885,14 @@ async function resolveDispatchCeiling(context, dependencies, options) {
         status: shouldBlock ? 'blocked' : 'unresolved',
         provider,
         value: null,
+        policyMode: null,
+        policy: null,
         source: null,
         preset: null,
         unresolved: true,
         projectPath,
         providerDefaultEffort,
+        matrix: null,
         providers,
         message,
     };
@@ -365,24 +903,39 @@ 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) {
+async function resolveCeilingValue(provider, resolvedConfig, projectPath, dependencies, escalationLevel) {
     const configCeiling = readResolvedConfigCeiling(provider, resolvedConfig);
-    if (configCeiling) {
-        return {
-            value: configCeiling.value,
-            source: configCeiling.source,
-            preset: null,
-        };
-    }
     const projectCeiling = await resolveProjectStateCeiling(provider, projectPath, dependencies);
-    if (projectCeiling) {
+    const baseCeiling = configCeiling ?? projectCeiling;
+    if (!baseCeiling) {
+        return null;
+    }
+    if (baseCeiling.mode === 'inherit' || baseCeiling.policy === 'uncapped') {
+        return baseCeiling;
+    }
+    const tier = policyTier(baseCeiling.policy);
+    const matrixCell = resolveProviderMatrixCell(provider, tier, resolvedConfig, projectCeiling?.matrix ?? null, escalationLevel);
+    if (matrixCell) {
         return {
-            value: projectCeiling.value,
-            source: 'project-state',
-            preset: projectCeiling.preset,
+            ...baseCeiling,
+            value: matrixCell.value,
+            cellSource: matrixCell.cellSource,
+            target: matrixCell.target,
+            selectionBranch: matrixCell.selectionBranch,
         };
     }
-    return null;
+    if (baseCeiling.policy !== 'legacy-ceiling' &&
+        baseCeiling.value === null &&
+        providerValueOrder(provider) === null) {
+        return null;
+    }
+    return baseCeiling;
+}
+function policyLabel(policy) {
+    if (policy === 'legacy-ceiling') {
+        return 'legacy capped';
+    }
+    return policy ?? 'inherit host defaults';
 }
 function writeHumanResolution(context, resolution) {
     const label = providerLabel(resolution.provider);
@@ -390,15 +943,48 @@ function writeHumanResolution(context, resolution) {
         context.logger.error(resolution.message);
         return;
     }
-    context.logger.info(`${label} dispatch ceiling: ${resolution.value ?? 'unresolved'}`);
+    context.logger.info(`${label} dispatch policy: ${policyLabel(resolution.policy)}`);
+    context.logger.info(`Resolved cap: ${resolution.value ?? 'none'}`);
     context.logger.info(`Source: ${sourceLabel(resolution.source)}`);
     const providerResolution = resolution.providers[resolution.provider];
     if (providerResolution) {
         context.logger.info(`Mode: ${providerResolution.mode} (${providerResolution.mechanism})`);
+        context.logger.info(`Selection: ${providerResolution.selection.selectionMode}`);
+        if (providerResolution.target) {
+            const details = [
+                `harness=${providerResolution.target.harness}`,
+                providerResolution.target.model
+                    ? `model=${providerResolution.target.model}`
+                    : null,
+                providerResolution.target.effort
+                    ? `effort=${providerResolution.target.effort}`
+                    : null,
+            ]
+                .filter(Boolean)
+                .join(' ');
+            const suffix = providerResolution.target.crossHarness
+                ? ' (cross-harness target; native dispatch args deferred)'
+                : '';
+            context.logger.info(`Dispatch target: ${details}${suffix}`);
+        }
     }
     if (resolution.provider === 'codex') {
         context.logger.info(`Codex provider default effort: ${resolution.providerDefaultEffort}`);
-        context.logger.info(`Note: OAT will use pinned subagent variants up to ${resolution.value ?? 'the resolved ceiling'}. Base/unpinned roles resolve through the provider default.`);
+        if (providerResolution?.selection.selectionMode === 'inherit-default') {
+            context.logger.info('Note: OAT will not select a Codex effort; base/unpinned roles resolve through the provider default.');
+        }
+        else if (providerResolution?.selection.selectionMode === 'uncapped') {
+            context.logger.info('Note: OAT will use the preferred pinned Codex variant with no configured cap. Actual host support for upward effort selection must be verified by the dispatching host.');
+        }
+        else if (providerResolution?.selection.selectionMode === 'review-target') {
+            context.logger.info('Note: Reviewer dispatch uses the configured target from the resolved capped policy.');
+        }
+        else if (providerResolution?.selection.selectionMode === 'no-review-target') {
+            context.logger.info('Note: Managed uncapped reviewer dispatch has no configured target; use the base/unpinned reviewer fallback.');
+        }
+        else {
+            context.logger.info(`Note: OAT will use pinned subagent variants up to ${resolution.value ?? 'the resolved policy cap'}. Base/unpinned roles resolve through the provider default.`);
+        }
         if (providerResolution?.selection.selectedValue &&
             providerResolution.selection.preferredValue) {
             context.logger.info(`Selected Codex effort: ${providerResolution.selection.selectedValue}`);
@@ -406,6 +992,9 @@ function writeHumanResolution(context, resolution) {
     }
     else {
         context.logger.info('Effort axis: not-applicable');
+        if (providerResolution?.selection.selectionMode === 'inherit-default') {
+            context.logger.info('Note: OAT will not select a Claude model; Task dispatch inherits host/provider behavior.');
+        }
         if (providerResolution?.selection.selectedValue &&
             providerResolution.selection.preferredValue) {
             context.logger.info(`Selected dispatch value: ${providerResolution.selection.selectedValue}`);
@@ -441,12 +1030,13 @@ export function createProjectDispatchCeilingCommand(overrides = {}) {
     };
     const command = new Command('dispatch-ceiling').description('Resolve OAT project dispatch ceiling metadata');
     command.addCommand(new Command('resolve')
-        .description('Resolve dispatch ceiling for a provider')
-        .requiredOption('--provider <provider>', 'Provider name: codex or claude are enforced; any other provider resolves as advisory (unsupported)')
+        .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')
         .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 capping by the resolved ceiling')
-        .option('--project-path <path>', 'Read project-state ceiling from an explicit project path')
+        .option('--preferred <value>', 'Preferred implementer/fix dispatch value before applying the resolved policy')
+        .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('--json', 'Output machine-readable JSON')