AI: only untap a permanent when it makes a concrete difference

[liamiak]

The problem

When no priority target (Time Vault-style "won't auto-untap") is present, UntapAi fell through to getMostExpensivePermanentAI — untapping the priciest tapped permanent whether or not untapping it achieved anything. For a card like Kiora's Follower that meant tapping it every turn to untap a land that untaps itself next turn regardless: motion with no value. That crudeness is why ~40 cards with a plain {T}: untap ability carry AI:RemoveDeck:All, which removes them from AI decks entirely.

The change

For free ({T}-only) untap abilities, pick a benefit-directed target — untap as late as possible, only for a concrete reason, and untap the exact card that reason points to:

• Ramp (own main): untap a mana source if and only if untapping that specific source turns a spell in hand we can't currently afford into one we can — verified with the real mana-payment routine (canPayManaCost), so it respects the actual cost, colours included, not just mana value.
• Blocker (opponent's turn): untap our best creature only while actually under attack.
• Otherwise: hold.

Costed / triggered / Always-logic untaps are a deliberate investment and keep their existing behaviour byte-for-byte.

Behaviour, free untappers (before → after)

situation	before	after
tapped land, nothing to cast	untap (waste)	hold
untapping a source affords a spell	untap	untap that source
ramp justified, but a creature is also tapped	untap the creature	untap the source
source untapped still can't afford the spell	untap (waste)	hold
idle tapped creature, own turn	untap (waste)	hold
under attack	untap	untap (blocker)
Time Vault / won't-auto-untap	untap	untap (unchanged)

Cards taken off AI:RemoveDeck:All

The improved logic makes six clean {T}-untap cards playable, so this drops the flag on all of them: Aphetto Alchemist, Kiora's Follower, Unbender Tine, Vizier of Tumbling Sands, Krosan Restorer, Tidewater Minion. Each was verified to untap only for genuine ramp/blocker benefit and hold otherwise.

Kept flagged: combo/return-cost pieces, and Ith, High Arcanist, whose untap is a combat damage-prevention trick rather than the ramp/blocker pattern.

Validation

Full desktop suite green (286). A characterization pass across free and costed untappers confirms every free-untap waste case now holds, every genuine benefit still fires, and costed untappers are unchanged.

Follow-up (not in this PR)

Two things are deliberately deferred to a follow-up:

• Costed untap cards ({X}{T}, {1}{T}, and other non-free untappers still flagged). This change only affects free {T}-only untaps, so their flags are left in place until the follow-up gives them their own benefit logic — untapping is worth real mana under a different, tighter bar than a free tap.
• A general "untap to re-use this permanent's own tap-ability" scan (e.g. untap a Merfolk Looter to loot again) — the natural generalization of the ramp case, but it needs faithful reuse of each ability's own AI evaluation (its combat caution, timing and hand-state), which warrants its own change and test suite.

---

🤖 Implemented with the assistance of Claude Code (Opus).

[tool4ever]

code looks too unclean
also just redundant to doPoolExtraManaLogic...?

[liamiak]

Good calls, both — addressed in the last three commits.

• Unclean: the smell was a board poke — it flipped a card's tapped state to probe affordability and restored it in a finally. Replaced with a small shared helper, untappingEnablesACast, that models the freed mana by shaving generic off a copy of the cost (ManaCostBeingPaid#decreaseShard) and asking canPayManaCost against usable sources only. No tap/untap of real permanents.
• Redundant: you were right that it overlapped doPoolExtraManaLogic, so I routed the dorks through the same helper. That also surfaced a latent bug on the dork side: its old !hasEnoughManaSourcesToCast gate counts tapped sources, so when you're tapped out but source-rich it decided it had "enough" and declined to ramp — exactly the spot where untapping a land is what lets the spell resolve. The helper asks "can I pay with usable sources now, and would one more mana close the gap?" instead, which is a strict superset of the old firing (nothing that ramped before stops), and the whole forge.ai suite stays green.

Split into three commits — helper + generic path, then the dork routing/fix, then an optional test — so the fix and the test are separable.