Agony's mechanics and changes rely heavily on limited replenishment.
It is meant to emphasize the importance of each individual unit and make losses more costly.

Recently a tiered replenishment system was also introduced that makes it harder/longer for higher tier units to be replenished. This is to simulate how difficult it is to find high tier replacements.

A lot of new and existing mechanics are affecting replenishment. E.g. Agony's march malus effects.

The specific message "shades cannot replenish in mortal realm" is something I fix as it probably relates to an effect that is matched to an incorrect tooltip text.

--- so in short, it is intended but the tooltip needs to be updated and thanks for pointing it out ))

The thing is, I took my army into a region and occupied a ruin, and having been at sea I figured the units had lost 50% due to attrition. However, once back on land and occupying the settlement I could not replenish.

I took the army back to my home settlement, and lo and behold, noone could replenish, with plenty of needed stocks of resources? I thought maybe a bug, and went another 5 or 6 turns, nope, no replenishment.

Not only that I couldn't even make any new units as the recruitment button was greyed out, in my home settlement?

Sadly this is a game breaker no matter the immersion you meant to inject, it's definitely not working as intended and with my enemy neighbour with a 14 unit full replenished stack breathing down my neck.

Ok for anyone coming here to find out why they cannot replenish their units or recruit more. You don't have enough people in your settlements. Ganossa explained this and it makes perfect sense. Gone are the days of whack-a-mole all settlements, now you restricted in a realistic way and have top use your wits to survive, especially if you only have a small settlement to begin with.

Makes perfect sense.

It sounds good on paper, but it's not working well in my opinion. At least it's not working as intended. You're telling me that if I conquer cities I can't then force that population into my own cities? or I can't have migration/refugee's replenish the manpower in my home settlement? I would mention births, but assuming the game's quote on quote, timeline, takes place within 20 years or 30 years or so, yea it technically brakes immersion but...idk I feel like there needs to be a certain amount of people or population in the city that I can recruit from. Divide et impera does this quite well actually and so did the older total war games.

I am enjoying the mod so much, but the population system needs changes for sure.I shouldn't be able to not recruit an army or "force" people from a newly conquered settlement to fight for me.

You can recruit units in newly conquered settlements but it depends on how much population that settlement/region has.

Migrants are adding to the recruitment pool also and will be used up when recruiting.

You can also move population manually between regions by recruiting any unit and disbanding somewhere else. There is a specific citizen unit that is supposed to be used for manual movement of population. (you get it in the growth building chain)
For further away conquest, it is even adviced to bring 1x or 2x citizen units in order to have them settle in the newly occupied settlements for faster building and replenishment.

Further, you can recruit even from the population pool of you allies if you are having your army in their region.

Also important to note, a province that is not taxed has -1 to recruitment slots. So if the province itself would give you +1 recruitment slot (if more than 250 pop), not taxing the province would reduce it back to 0.