feat(mosstank): buff-caster preparer and single idle-peace arbiter — wield from the Items profile, enter magic/peace mode by itself

Implements docs/plans/2026-09-06-mosstank-mode-arbitration.md.

The buff pass used to fire TryCast with no regard for combat mode or
which caster was wielded. ACE's Player_Magic.cs:84-95 drops any cast
that arrives while CombatMode != Magic, and Player_Combat.cs:778+
(GetEquippedWand) requires a wielded caster before Magic mode can be
entered at all — so a buff pass started from Peace or Melee silently
cast nothing.

Design A: BuffCasterPreparer (new) is the single owner of "which
caster do we buff with and how do we get into Magic mode". It resolves
the wielded caster first, else the first profiled caster (same
membership predicate as VitalRecharge), wields it through Peace when
needed, then requests Magic — gating the buff queue on Ready. A
missing caster stops the pass with VTank's own notice, posted once
per Reset. A stuck mode request retries on a 2s cadence up to
VitalSettings.DropToPeaceModeRetryCount before stopping and naming the
stuck stage. Hosts that don't model combat-mode automation at all
(EnterMode returns Unavailable) bypass the gate rather than deadlock,
matching the existing TickEquipment convention for older/no-window
hosts.

Design B: MacroIdleModeArbiter (new) is the single owner of "Peace
Mode When Idle", deleting CombatController's own idle-peace branch.
The old branch only ran from CombatController's own no-target state,
which a disabled combat policy never reaches — so a running macro
with combat disabled never dropped to peace. The arbiter ticks after
every controller in MossTankPanel.OnTick and covers that case.

Tests 1-7 of the plan: BuffCasterPreparer (wielded-caster fast path,
wield-then-magic ordering, no-caster notice latch, exhausted retry
budget) and MacroIdleModeArbiter (retry gate, suppression, IdlePeaceMode
off, the disabled-combat case) are added to CombatControllerTests.cs,
reusing its FakeAutomation extended with deferred mode/equip
confirmation and a call log. A full buff-then-fight panel scenario is
added to MossTankPanelTests.cs via a new CombatCapableFakeAutomation.
CombatControllerTests' IdlePeaceIsTheNoTargetFallback is deleted and
re-pinned on the arbiter. Every new test was confirmed to fail (by
compile error or by runtime assertion) against the unmodified
production code via a temporary git stash before its fix landed.

337 -> 345 AcDream.Plugins.MossTank.Tests (336 baseline sans the moved
test, plus 9 new); AcDream.App.Tests MossTank/Plugin filter (79 tests,
including MossTankMarkupContractTests) stays green with no markup
changes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

src/AcDream.Plugins.MossTank/BuffCasterPreparer.cs

@@ -0,0 +1,274 @@
+using AcDream.Plugin.Abstractions;
+
+namespace AcDream.Plugins.MossTank;
+
+/// <summary>
+/// Gets the character ready to cast before a buff pass's first
+/// <c>TryCast</c>: resolve which caster to buff with, wield it if it is not
+/// already equipped, and enter Magic mode. Retail drops any cast that
+/// arrives outside Magic mode (ACE <c>Player_Magic.cs:84-95</c>), and Magic
+/// mode itself requires a wielded caster (ACE
+/// <c>Player_Combat.cs:778+</c>, <c>GetEquippedWand</c>) — the buff pass
+/// used to assume both were already true. This is the single owner of
+/// "which caster do we buff with and how do we get into Magic mode"; see
+/// <c>docs/plans/2026-09-06-mosstank-mode-arbitration.md</c> Design A.
+/// </summary>
+internal sealed class BuffCasterPreparer
+{
+    /// <summary>
+    /// Retail's caster ITEM_TYPE bit (VTank's <c>CasterItemType</c>,
+    /// <see cref="VitalRecharge"/>'s recovery-caster predicate, and
+    /// <see cref="CombatController.SelectRecoveryCaster"/> all use the same
+    /// constant).
+    /// </summary>
+    private const uint CasterItemType = 0x00008000u;
+
+    /// <summary>
+    /// Mirrors <see cref="CombatController.TryEquipIfNeeded"/>'s retry
+    /// budget in spirit (same <see cref="VitalSettings.DropToPeaceModeRetryCount"/>
+    /// constant), but on a fixed wall-clock cadence rather than once per
+    /// combat tick — a buff pass is not scanning for targets every 0.25 s,
+    /// so re-issuing a stuck mode request needs its own pacing.
+    /// </summary>
+    private const double ModeRetrySeconds = 2.0;
+
+    private readonly IPluginHost _host;
+    private readonly CombatSettings _settings;
+    private readonly VitalSettings _vitalSettings;
+
+    private PluginCombatMode? _pendingRequestedMode;
+    private double _modeWaitElapsed;
+    private int _modeRetryCount;
+
+    /// <summary>
+    /// Posting VTank's "no wand" notice is latched so an automatic scan that
+    /// keeps finding no caster does not spam chat every scan interval. The
+    /// latch clears only on <see cref="Reset"/> (Stop, session end, or macro
+    /// stop) — the simplest honest rule: it re-announces once per fresh
+    /// attempt at running the macro, not on every failed scan in between.
+    /// </summary>
+    private bool _noCasterNoticePosted;
+
+    public BuffCasterPreparer(
+        IPluginHost host,
+        CombatSettings settings,
+        VitalSettings? vitalSettings = null)
+    {
+        _host = host ?? throw new ArgumentNullException(nameof(host));
+        _settings = settings ?? throw new ArgumentNullException(nameof(settings));
+        _vitalSettings = vitalSettings ?? new VitalSettings();
+    }
+
+    /// <summary>The buff queue may run once this is true.</summary>
+    public bool Ready { get; private set; }
+
+    /// <summary>
+    /// The pass must stop (no caster, an equip/mode refusal, or an
+    /// exhausted retry budget). <see cref="Status"/> names why.
+    /// </summary>
+    public bool Stopped { get; private set; }
+
+    public string Status { get; private set; } = string.Empty;
+
+    /// <summary>
+    /// Ticked every frame while the buff pass runs, before its first
+    /// <c>TryCast</c>. A no-op once <see cref="Ready"/> or
+    /// <see cref="Stopped"/>.
+    /// </summary>
+    public void Tick(double elapsedSeconds)
+    {
+        if (Ready || Stopped)
+            return;
+
+        IAutomationSurface automation = _host.Automation;
+        IEquipmentAutomation equipment = automation.Equipment;
+
+        // Older/no-window hosts report unavailable rather than modelling
+        // equipment at all (the same convention as
+        // CombatController.TickEquipment); do not turn a missing optional
+        // projection into a permanent deadlock for every buff pass.
+        if (equipment.IsAvailable)
+        {
+            if (equipment.IsBusy)
+            {
+                Status = "Equipping caster";
+                return;
+            }
+
+            if (!TryResolveCaster(equipment.CaptureOwnedEquipment(), out PluginEquipmentItem caster))
+            {
+                StopWithNoCasterNotice();
+                return;
+            }
+
+            if (!caster.IsEquipped)
+            {
+                PluginCombatMode wieldMode = automation.Combat.Snapshot.Mode;
+                if (wieldMode != PluginCombatMode.Peace)
+                {
+                    RequestMode(
+                        PluginCombatMode.Peace,
+                        elapsedSeconds,
+                        "could not enter peace mode to equip a caster");
+                    return;
+                }
+
+                ResetModeWait();
+                PluginEquipmentCommandResult equip = equipment.Equip(caster.ObjectId);
+                if (equip.Status == PluginEquipmentCommandStatus.Refused)
+                {
+                    Stop(equip.Notice ?? $"Cannot equip {caster.Name}.");
+                    return;
+                }
+                Status = $"Equipping {caster.Name}";
+                return;
+            }
+        }
+
+        PluginCombatMode currentMode = automation.Combat.Snapshot.Mode;
+        if (currentMode != PluginCombatMode.Magic)
+        {
+            RequestMode(PluginCombatMode.Magic, elapsedSeconds, "could not enter magic mode");
+            return;
+        }
+
+        Ready = true;
+        Status = "Ready to buff";
+    }
+
+    /// <summary>Reset on Stop, on session end, and when the macro stops.</summary>
+    public void Reset()
+    {
+        Ready = false;
+        Stopped = false;
+        Status = string.Empty;
+        _pendingRequestedMode = null;
+        _modeWaitElapsed = 0d;
+        _modeRetryCount = 0;
+        _noCasterNoticePosted = false;
+    }
+
+    /// <summary>
+    /// Wielded caster first (retail's actual equipped wand); else the first
+    /// profiled caster, ordered by name then object id for a deterministic
+    /// choice. <c>_noBuffItemNames</c> (VTank's "do not cast item
+    /// enchantments on this weapon") is not a caster exclusion — that flag
+    /// is about weapon procs, not who may buff.
+    /// </summary>
+    private bool TryResolveCaster(
+        IReadOnlyList<PluginEquipmentItem> items,
+        out PluginEquipmentItem caster)
+    {
+        foreach (PluginEquipmentItem item in items)
+        {
+            if ((item.ItemType & CasterItemType) != 0u && item.IsEquipped)
+            {
+                caster = item;
+                return true;
+            }
+        }
+
+        PluginEquipmentItem? best = null;
+        foreach (PluginEquipmentItem item in items)
+        {
+            if ((item.ItemType & CasterItemType) == 0u)
+                continue;
+            if (!_settings.CombatItemObjectIds.Contains(item.ObjectId)
+                && !_settings.CombatItemNames.Contains(item.Name))
+            {
+                continue;
+            }
+            if (best is null
+                || string.CompareOrdinal(item.Name, best.Value.Name) < 0
+                || (string.Equals(item.Name, best.Value.Name, StringComparison.Ordinal)
+                    && item.ObjectId < best.Value.ObjectId))
+            {
+                best = item;
+            }
+        }
+
+        if (best is { } selected)
+        {
+            caster = selected;
+            return true;
+        }
+        caster = default;
+        return false;
+    }
+
+    private void StopWithNoCasterNotice()
+    {
+        const string notice = "You must add at least one wand to your Items profile.";
+        Stopped = true;
+        Status = notice;
+        if (_noCasterNoticePosted)
+            return;
+        _host.Automation.Chat.PostSystemMessage("[MossTank] " + notice);
+        _noCasterNoticePosted = true;
+    }
+
+    private void Stop(string status)
+    {
+        Stopped = true;
+        Status = status;
+    }
+
+    private void ResetModeWait()
+    {
+        _pendingRequestedMode = null;
+        _modeWaitElapsed = 0d;
+        _modeRetryCount = 0;
+    }
+
+    /// <summary>
+    /// Issue (or re-issue) one mode request, gated to at most once per
+    /// <see cref="ModeRetrySeconds"/> and at most
+    /// <see cref="VitalSettings.DropToPeaceModeRetryCount"/> times; the
+    /// exhausted budget stops the pass naming the stage.
+    /// </summary>
+    private void RequestMode(PluginCombatMode mode, double elapsedSeconds, string exhaustedStatus)
+    {
+        if (_pendingRequestedMode != mode)
+        {
+            _pendingRequestedMode = mode;
+            _modeWaitElapsed = 0d;
+            _modeRetryCount = 1;
+            IssueModeRequest(mode);
+            return;
+        }
+
+        _modeWaitElapsed += Math.Max(0d, elapsedSeconds);
+        if (_modeWaitElapsed < ModeRetrySeconds)
+        {
+            Status = $"Entering {mode} mode";
+            return;
+        }
+
+        _modeWaitElapsed = 0d;
+        _modeRetryCount++;
+        if (_modeRetryCount > _vitalSettings.DropToPeaceModeRetryCount)
+        {
+            Stop(exhaustedStatus);
+            return;
+        }
+        IssueModeRequest(mode);
+    }
+
+    private void IssueModeRequest(PluginCombatMode mode)
+    {
+        PluginCombatCommandResult result = _host.Automation.Combat.EnterMode(mode);
+        if (result.Status == PluginCombatCommandStatus.Unavailable)
+        {
+            // The host does not model combat-mode automation at all (an
+            // older/no-window host projects only NoOpAutomationSurface
+            // here). Do not turn a missing optional projection into a
+            // permanent deadlock for every buff pass; proceed as ready.
+            Ready = true;
+            Status = "Ready to buff";
+            return;
+        }
+        Status = result.Status == PluginCombatCommandStatus.Refused
+            ? result.Notice ?? $"Cannot enter {mode} mode"
+            : $"Entering {mode} mode";
+    }
+}

src/AcDream.Plugins.MossTank/CombatController.cs

@@ -269,19 +269,12 @@ internal sealed class CombatController
 
         if (_targetId == 0u)
         {
+            // Peace-Mode-When-Idle is owned solely by MacroIdleModeArbiter,
+            // which ticks after every controller (including this one) and so
+            // also covers the case this controller cannot see: combat policy
+            // disabled but the macro still running. See
+            // docs/plans/2026-09-06-mosstank-mode-arbitration.md Design B.
             StopApproachMovement();
-            PluginCombatSnapshot idle = _host.Automation.Combat.Snapshot;
-            if (_settings.IdlePeaceMode
-                && idle.Mode is not (PluginCombatMode.Unknown
-                    or PluginCombatMode.Peace))
-            {
-                PluginCombatCommandResult result =
-                    _host.Automation.Combat.EnterMode(PluginCombatMode.Peace);
-                Status = result.Status == PluginCombatCommandStatus.Refused
-                    ? result.Notice ?? "Cannot enter peace mode"
-                    : "Entering peace mode";
-                return;
-            }
             Status = "Waiting for a target";
             return;
         }

src/AcDream.Plugins.MossTank/MacroIdleModeArbiter.cs

@@ -0,0 +1,72 @@
+using AcDream.Plugin.Abstractions;
+
+namespace AcDream.Plugins.MossTank;
+
+/// <summary>
+/// The single owner of VTank's "Peace Mode When Idle": with the macro
+/// running and no controller doing anything this tick, drop to Peace mode.
+/// Ticked from <see cref="MossTankPanel.OnTick"/> after every other
+/// controller has ticked, so it also fires when combat is disabled — the
+/// case <see cref="CombatController"/>'s own idle-peace branch missed,
+/// because that branch only ran once combat had reached its no-target
+/// state, which a disabled combat policy never reaches. See
+/// <c>docs/plans/2026-09-06-mosstank-mode-arbitration.md</c> Design B.
+/// </summary>
+internal sealed class MacroIdleModeArbiter
+{
+    /// <summary>
+    /// Re-issue at most this often while the idle condition holds. VTank's
+    /// idle-peace request does not need combat's 0.25 s scan cadence; a
+    /// slower, gentler retry avoids hammering a refused request.
+    /// </summary>
+    private const double IdleRetrySeconds = 1.0;
+
+    private readonly IPluginHost _host;
+    private readonly CombatSettings _settings;
+
+    /// <summary>Starts armed so the first idle tick can request immediately.</summary>
+    private double _sinceLastRequest = IdleRetrySeconds;
+
+    public MacroIdleModeArbiter(IPluginHost host, CombatSettings settings)
+    {
+        _host = host ?? throw new ArgumentNullException(nameof(host));
+        _settings = settings ?? throw new ArgumentNullException(nameof(settings));
+    }
+
+    /// <summary>Last request's outcome, or null while the arbiter is inactive.</summary>
+    public string? Status { get; private set; }
+
+    /// <param name="macroRunning">VTank's Run Macro toggle (not the combat policy Enabled flag).</param>
+    /// <param name="idle">
+    /// True when nothing else owns this tick: no buff pass, not casting, no
+    /// controller's own owns-action flag, no hostile target, and equipment
+    /// is not mid-swap.
+    /// </param>
+    public void Tick(double elapsedSeconds, bool macroRunning, bool idle)
+    {
+        _sinceLastRequest += Math.Max(0d, elapsedSeconds);
+
+        if (!macroRunning || !_settings.IdlePeaceMode || !idle)
+        {
+            Status = null;
+            return;
+        }
+
+        PluginCombatMode mode = _host.Automation.Combat.Snapshot.Mode;
+        if (mode is PluginCombatMode.Peace or PluginCombatMode.Unknown)
+        {
+            Status = null;
+            return;
+        }
+
+        if (_sinceLastRequest < IdleRetrySeconds)
+            return;
+
+        _sinceLastRequest = 0d;
+        PluginCombatCommandResult result =
+            _host.Automation.Combat.EnterMode(PluginCombatMode.Peace);
+        Status = result.Status == PluginCombatCommandStatus.Refused
+            ? result.Notice ?? "Cannot enter peace mode"
+            : "Entering peace mode";
+    }
+}

src/AcDream.Plugins.MossTank/MossTankPanel.cs

@@ -54,6 +54,8 @@ internal sealed partial class MossTankPanel
     private readonly MossTankMetaProfileStore _metaProfiles;
     private readonly MetaViewManager _metaViews;
     private readonly CombatController _combat;
+    private readonly BuffCasterPreparer _buffCasterPreparer;
+    private readonly MacroIdleModeArbiter _idleModeArbiter;
     private readonly VitalRechargeController _vitalRecharge;
     private readonly DispelController _dispel;
     private readonly InventoryMaintenanceController _inventoryMaintenance;
@@ -203,6 +205,11 @@ internal sealed partial class MossTankPanel
         if (!_routeProfiles.LoadCurrent(_navigationSettings))
             _routeProfiles.SaveCurrent(_navigationSettings);
         _combat = new CombatController(host, _combatSettings, _vitalSettings);
+        _buffCasterPreparer = new BuffCasterPreparer(
+            host,
+            _combatSettings,
+            _vitalSettings);
+        _idleModeArbiter = new MacroIdleModeArbiter(host, _combatSettings);
         _vitalRecharge = new VitalRechargeController(
             host,
             _vitalSettings,
@@ -3665,6 +3672,7 @@ internal sealed partial class MossTankPanel
         _queueIndex = 0;
         _status = status;
         RestoreSelection();
+        _buffCasterPreparer.Reset();
     }
 
     private void RestoreSelection()
@@ -3710,6 +3718,7 @@ internal sealed partial class MossTankPanel
         // A stopped VTank macro owns no movement or staged maintenance work.
         // Worn-mana upkeep is intentionally not reset: VTank's
         // ManaChargesWhenOff option permits that one controller to continue.
+        _buffCasterPreparer.Reset();
         _vitalRecharge.Reset();
         _dispel.Reset();
         _inventoryMaintenance.Reset();
@@ -3896,13 +3905,38 @@ internal sealed partial class MossTankPanel
                 || randomHelperOwnsAction
                 || (navigationOwnsAction && _navigationSettings.Priority));
         _combat.OnTick(elapsedSeconds, _navigationSettings.Enabled);
+
+        IAutomationSurface automation = _host.Automation;
+        // MacroIdleModeArbiter is the single owner of "peace when idle"; it
+        // ticks here — after every controller above, including combat —
+        // so it also fires with combat policy disabled, which
+        // CombatController's own no-target branch could never reach.
+        _idleModeArbiter.Tick(
+            elapsedSeconds,
+            macroRunning,
+            idle: !_running
+                && !automation.Magic.IsCasting
+                && !commandJumpOwnsAction
+                && !giveOwnsAction
+                && !criticalCraftOwnsAction
+                && !vitalOwnsAction
+                && !dispelOwnsAction
+                && !manaRechargeOwnsAction
+                && !lootOwnsAction
+                && !craftingOwnsAction
+                && !idleCraftingOwnsAction
+                && !inventoryOwnsAction
+                && !navigationOwnsAction
+                && !randomHelperOwnsAction
+                && !_combat.HasTarget
+                && !automation.Equipment.IsBusy);
+
         if (_activeTab == TankTab.Route)
             RefreshRouteEditor();
 
         if (!_running)
             return;
 
-        IAutomationSurface automation = _host.Automation;
         if (!automation.IsAvailable)
         {
             Stop("Lost the session.");
@@ -3945,6 +3979,23 @@ internal sealed partial class MossTankPanel
         if (giveOwnsAction)
             return;
 
+        // BuffCasterPreparer is the single owner of "which caster do we
+        // buff with and how do we get into Magic mode"; TryCast never runs
+        // until it reports Ready.
+        _buffCasterPreparer.Tick(elapsedSeconds);
+        if (_buffCasterPreparer.Stopped)
+        {
+            string reason = _buffCasterPreparer.Status;
+            Stop(reason);
+            _host.Log.Warn($"MossTank: buff pass stopped by preparer — {reason}");
+            return;
+        }
+        if (!_buffCasterPreparer.Ready)
+        {
+            _status = _buffCasterPreparer.Status;
+            return;
+        }
+
         if (_queueIndex >= _queue.Count)
         {
             bool announce = _announceBuffPass;
@@ -4147,6 +4198,7 @@ internal sealed partial class MossTankPanel
         _queueIndex = 0;
         _selectionBeforePass = null;
         _status = "Lost the session.";
+        _buffCasterPreparer.Reset();
         ResetSessionScopedControllers();
     }