feat(tyrant): add arena boss succession

design/concepts/game-state-machine.md

@@ -8,31 +8,32 @@ description: Defines lifecycle, succession, selection, and pause behavior for a
 
 ## Lifecycle
 
-The game begins unstarted. An administrator starts it by assigning the first Tyrant; the administrator may explicitly assign the first Vigilante or allow selection from eligible recently active players. A running game may be paused without deleting its state and later resumed.
+The game begins unstarted. An administrator starts it by assigning the first Tyrant; the administrator may explicitly assign the first Vigilante or leave that role vacant for the blue arena challenge. A running game may be paused without deleting its state and later resumed.
 
 Pausing freezes gameplay progression, role inactivity checks, pending-selection deadlines, ability cooldowns, and daily-use timers. Role and class effects are suppressed while paused and restored on resume.
 
 ## Tyrant succession
 
-When a player directly kills the Tyrant, that killer becomes the new Tyrant. When no player is credited with the death, an eligible opted-in player active during the preceding 24 hours is selected randomly. The former Tyrant is excluded when another candidate exists.
+When a player directly kills the Tyrant, that killer becomes the new Tyrant immediately. When no player is credited with the death, or when the Tyrant becomes inactive or relinquishes, the reign ends and the Tyrant role remains vacant for the shared arena challenge. The former Tyrant may compete again under the same rules as other opted-in participants.
 
-Every Tyrant death ends the reign, clears all role-side assignments, resets the former Tyrant's reign progression, and leaves the Vigilante role open for the arena challenge. The new Tyrant receives one starting unlock choice.
+Every ended Tyrant reign clears all role-side assignments and resets reign progression. The shared arena presents the Tyrant challenge first with a red particle boundary. Its winner becomes Tyrant at level zero with one starting unlock choice; only then may a vacant Vigilante role open the blue challenge at the same location.
 
 ## Vigilante succession
 
 Every Vigilante death ends that assignment regardless of cause. Vigilante inactivity and relinquishment also end the assignment, and every new Tyrant reign clears the previous assignment. Followers are cleared rather than transferred.
 
-While the game is running with an active Tyrant and no Vigilante, an administrator-configured arena opens. One eligible opted-in non-Tyrant player at a time may challenge the arena boss. Defeating it assigns that player as Vigilante. Leaving, disconnecting, or dying resets the fight without preventing an immediate retry. Without an active Tyrant or configured arena, the role remains vacant and no boss exists.
+While the game is running with an active Tyrant, no open Tyrant challenge, and no Vigilante, the administrator-configured arena opens its Vigilante challenge. One eligible opted-in non-Tyrant player at a time may challenge the arena boss. Defeating it assigns that player as Vigilante. Leaving, disconnecting, or dying resets the fight without preventing an immediate retry. Without an active Tyrant or configured arena, the role remains vacant and no boss exists.
 
 A Tyrant earns progression from a Vigilante death only when the Tyrant personally killed the Vigilante.
 
 ## Pending selections
 
-An offline randomly selected Tyrant has 24 hours of unpaused time to log in and confirm the assignment. Failure causes another Tyrant selection. When no eligible Tyrant candidate exists, the position remains vacant and selection retries periodically. Vigilante vacancies use the arena rather than pending random selection.
+New random and pending role selections are not created. Legacy pending Tyrant or Vigilante selections are cleared into the applicable arena vacancy without granting a role. A Tyrant vacancy has priority, so the two role challenges cannot run concurrently.
 
 ## Related stories
 
 - [Start, pause, and administer the game](../user-stories/us-001-start-pause-and-administer.md)
 - [Transfer and reset the Tyrant role](../user-stories/us-002-transfer-and-reset-tyrant.md)
-- [Handle inactivity and pending selections](../user-stories/us-010-handle-inactivity-and-selection.md)
+- [Handle inactivity and arena vacancies](../user-stories/us-010-handle-inactivity-and-selection.md)
 - [Claim the Vigilante role in the arena](../user-stories/us-019-claim-vigilante-in-arena.md)
+- [Claim the Tyrant role in the arena](../user-stories/us-020-claim-tyrant-in-arena.md)

design/concepts/persistence-model.md

@@ -6,7 +6,7 @@ description: Defines the durable state and timekeeping needed to restore a Tyran
 
 # Persistence Model
 
-State is keyed by player UUID while retaining the latest known player name for display. Durable global state includes lifecycle status, current and pending role holders, selection deadlines, paused durations, the current Tyrant reign, and the administrator-configured Vigilante arena center. Active boss and challenger entities are transient and are reconstructed or reset from authoritative role and arena state after restart.
+State is keyed by player UUID while retaining the latest known player name for display. Durable global state includes lifecycle status, current and pending role holders, selection deadlines, paused durations, the current Tyrant reign, and the administrator-configured Vigilante arena center. Active Tyrant or Vigilante challenge bosses and challenger entities are transient and are reconstructed or reset from authoritative role and shared-arena state after restart.
 
 Durable player state includes participation status, opt-out deadline, login history, role or class, Tyrant level, purchased unlocks, unspent choices, Follower relationship, ability cooldowns, daily intelligence use, bound-item delivery state, and captured mobs.
 
@@ -18,3 +18,4 @@ Elapsed-time rules use UTC instants. Paused time is excluded from timers. Saves
 - [Configure and persist game state](../user-stories/us-012-configure-and-persist-state.md)
 - [Use class ability items](../user-stories/us-014-use-class-ability-items.md)
 - [Claim the Vigilante role in the arena](../user-stories/us-019-claim-vigilante-in-arena.md)
+- [Claim the Tyrant role in the arena](../user-stories/us-020-claim-tyrant-in-arena.md)

design/concepts/role-and-class-model.md

@@ -8,7 +8,7 @@ description: Defines Tyrant-side classes, Vigilante-side membership, progression
 
 ## Roles and affiliations
 
-A running game has one active or pending Tyrant. It has at most one Vigilante, and a vacant Vigilante role remains open until an eligible player wins the configured arena challenge. The Vigilante may recruit Followers through invitations that require acceptance. The Tyrant may assign the Assassin, Fixer, and Tamer classes after unlocking them.
+A running game has at most one Tyrant and at most one Vigilante. A vacant Tyrant role takes priority in the shared arena; after its winner becomes Tyrant, a vacant Vigilante role may use the same arena. The Vigilante may recruit Followers through invitations that require acceptance. The Tyrant may assign the Assassin, Fixer, and Tamer classes after unlocking them.
 
 Role alignment and Tyrant-side class are independent. A Vigilante or Follower may simultaneously hold one Tyrant-side class, allowing divided loyalties. A player cannot simultaneously be the Tyrant, Vigilante, and/or a Follower, and cannot hold more than one Tyrant-side class. Each Tyrant-side class may be assigned to only one player at a time. Opted-out players are ineligible for every assignment.
 
@@ -37,3 +37,4 @@ Vigilante Follower scaling is capped by default at Strength V and Resistance IV,
 - [Assign unlocked classes](../user-stories/us-004-assign-unlocked-classes.md)
 - [Support the Vigilante and Followers](../user-stories/us-008-support-vigilante-and-followers.md)
 - [Claim the Vigilante role in the arena](../user-stories/us-019-claim-vigilante-in-arena.md)
+- [Claim the Tyrant role in the arena](../user-stories/us-020-claim-tyrant-in-arena.md)

design/index.md

@@ -13,6 +13,7 @@ This bundle documents the asymmetric Tyrant game, its role succession, class abi
 
 - [User stories](user-stories/index.md)
 - [Vigilante arena challenge](user-stories/us-019-claim-vigilante-in-arena.md)
+- [Tyrant arena challenge](user-stories/us-020-claim-tyrant-in-arena.md)
 - [Game state machine](concepts/game-state-machine.md)
 - [Role and class model](concepts/role-and-class-model.md)
 - [Persistence model](concepts/persistence-model.md)

design/log.md

@@ -6,6 +6,14 @@ description: Chronological record of material decisions affecting the Spigot Tyr
 
 # Spigot Tyrant Design Log
 
+## 2026-08-23 — Shared Tyrant and Vigilante arena succession completed
+
+- Completed US-020 and reopened related succession, inactivity, administration, configuration, and Vigilante-arena stories so non-player Tyrant replacement is earned rather than random.
+- Environmental Tyrant death, inactivity, and relinquishment now clear the reign and open the shared one-player Tyrant boss challenge; a directly credited player killer still succeeds immediately.
+- The shared arena prioritizes a vacant Tyrant with a red particle circle, then opens a vacant Vigilante challenge with a blue circle after a Tyrant becomes active; neutral particles remain while neither challenge is open.
+- Both roles share the configured location, boss balance, barriers, containment, mob exclusion, reset behavior, notifications, and restart protections, while an active Tyrant remains unable to enter.
+- Removed new random and pending role selection, retained safe migration of legacy pending state and the legacy maintenance-interval configuration key, and verified 115 automated tests plus `./gradlew clean check jar`.
+
 ## 2026-08-23 — Vigilante arena succession completed
 
 - Completed US-019 and reopened related administration, Vigilante, inactivity, participation, persistence, control-panel, and completion stories to replace automatic Vigilante selection with an earned arena challenge.

design/user-stories/index.md

@@ -9,7 +9,7 @@
 7. [US-007: Capture and place mobs as a Tamer](us-007-capture-and-place-mobs.md)
 8. [US-008: Support the Vigilante and Followers](us-008-support-vigilante-and-followers.md)
 9. [US-009: Purchase and use Tyrant abilities](us-009-use-tyrant-abilities.md)
-10. [US-010: Handle inactivity and pending selections](us-010-handle-inactivity-and-selection.md)
+10. [US-010: Handle inactivity and arena vacancies](us-010-handle-inactivity-and-selection.md)
 11. [US-011: Inform players and manage participation](us-011-inform-and-manage-participation.md)
 12. [US-012: Configure and persist game state](us-012-configure-and-persist-state.md)
 13. [US-013: Build, test, and release the plugin](us-013-build-test-and-release.md)
@@ -19,3 +19,4 @@
 17. [US-017: Use bound role control items](us-017-use-bound-role-control-items.md)
 18. [US-018: Complete Tyrant commands contextually](us-018-complete-commands-contextually.md)
 19. [US-019: Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)
+20. [US-020: Claim the Tyrant role in the arena](us-020-claim-tyrant-in-arena.md)

design/user-stories/us-001-start-pause-and-administer.md

@@ -17,7 +17,7 @@ As a **server operator**, I want to start, pause, resume, and inspect the game s
 - [x] Pausing freezes progression, cooldowns, daily-use timers, inactivity checks, and pending-selection deadlines.
 - [x] Role and class effects are suppressed while paused and restored when play resumes.
 - [x] Administrative commands require the `spigottyrant.admin` permission, granted to server operators by default.
-- [x] Administrators can inspect lifecycle state, roles, classes, Followers, purchases, levels, cooldowns, participation, pending selections, and the configured Vigilante arena location.
+- [x] Administrators can inspect lifecycle state, roles, classes, Followers, purchases, levels, cooldowns, participation, legacy pending selections, and the configured shared role arena location.
 - [x] Destructive administrative operations require explicit confirmation.
 
 ## Related

design/user-stories/us-002-transfer-and-reset-tyrant.md

@@ -12,11 +12,11 @@ As a **player**, I want defeating the Tyrant to transfer power predictably so th
 ## Acceptance criteria
 
 - [x] A player directly credited with killing the Tyrant becomes the new Tyrant.
-- [x] A Tyrant death without a player killer selects an eligible opted-in player active within the preceding 24 hours at random.
-- [x] The former Tyrant is excluded from random succession when another eligible candidate exists.
+- [x] A Tyrant death without a player killer leaves the role vacant and opens the shared Tyrant arena challenge.
+- [x] The former Tyrant may compete again under the same arena eligibility and reset rules as every other opted-in participant.
 - [x] The former Tyrant's level, unlocks, unspent choices, and Tyrant ability cooldowns reset when the reign ends.
 - [x] Every Assassin, Fixer, Tamer, Vigilante, and Follower assignment is cleared when the Tyrant dies.
-- [x] A new Vigilante is selected under the normal candidate rules after succession.
+- [x] After Tyrant succession, a vacant Vigilante role opens the shared arena's Vigilante challenge.
 - [x] The new Tyrant receives exactly one starting unlock choice.
 - [x] The Tyrant's displayed name is red and the Tyrant has a red glowing outline while the game is running.
 - [x] Succession cannot assign the same player as both Tyrant and Vigilante.
@@ -25,3 +25,4 @@ As a **player**, I want defeating the Tyrant to transfer power predictably so th
 
 - [Tyrant game state machine](../concepts/game-state-machine.md)
 - [Progress and purchase Tyrant unlocks](us-003-progress-and-purchase-unlocks.md)
+- [Claim the Tyrant role in the arena](us-020-claim-tyrant-in-arena.md)

design/user-stories/us-008-support-vigilante-and-followers.md

@@ -31,6 +31,6 @@ As the **Vigilante**, I want nearby living Followers to strengthen me against th
 ## Related
 
 - [Role and class model](../concepts/role-and-class-model.md)
-- [Handle inactivity and pending selections](us-010-handle-inactivity-and-selection.md)
+- [Handle inactivity and arena vacancies](us-010-handle-inactivity-and-selection.md)
 - [Manage Followers through the Vigilante control panel](us-016-manage-vigilante-control-panel.md)
 - [Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)

design/user-stories/us-010-handle-inactivity-and-selection.md

@@ -1,25 +1,23 @@
 ---
 type: User Story
-title: "US-010: Handle inactivity and pending selections"
-description: Replace absent or unconfirmed role holders using recently active eligible players.
+title: "US-010: Handle inactivity and arena vacancies"
+description: Replace inactive role holders through the shared arena without granting legacy pending selections.
 status: done
 ---
 
-# US-010: Handle inactivity and pending selections
+# US-010: Handle inactivity and arena vacancies
 
 As a **participant**, I want inactive central roles to be replaced fairly so that the game does not stall around absent players.
 
 ## Acceptance criteria
 
 - [x] A Tyrant or Vigilante who has not logged in for 48 unpaused hours loses the position.
-- [x] Random candidates are drawn from eligible opted-in players who logged in during the preceding 24 hours.
+- [x] Tyrant and Vigilante vacancies use their shared arena challenges rather than random candidate selection.
 - [x] The Tyrant is always excluded from Vigilante selection.
-- [x] A previous role holder is excluded when another eligible candidate exists and may be reused only as a fallback.
-- [x] Tyrant inactivity ends the reign, clears all assignments, invokes normal random Tyrant succession, and opens the Vigilante arena challenge once a Tyrant is active.
+- [x] Previous role holders may compete for their former role under the same arena eligibility and reset rules as other opted-in participants.
+- [x] Tyrant inactivity ends the reign, clears all assignments, and opens the Tyrant arena challenge; the Vigilante challenge can open only after a Tyrant becomes active.
 - [x] Vigilante inactivity clears Followers and opens the Vigilante arena challenge without changing the Tyrant.
-- [x] An offline randomly selected candidate must log in within 24 unpaused hours to confirm the assignment.
-- [x] An unconfirmed Tyrant selection expires and rerolls automatically under the same eligibility rules.
-- [x] Tyrant selection remains vacant and retries periodically when no valid candidate exists.
+- [x] Legacy pending role selections are cleared safely into the applicable arena vacancy without granting a role.
 - [x] Candidate selection cannot assign conflicting roles or choose an opted-out player, including during concurrent joins and deaths.
 
 ## Related
@@ -27,3 +25,4 @@ As a **participant**, I want inactive central roles to be replaced fairly so tha
 - [Tyrant game state machine](../concepts/game-state-machine.md)
 - [Inform players and manage participation](us-011-inform-and-manage-participation.md)
 - [Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)
+- [Claim the Tyrant role in the arena](us-020-claim-tyrant-in-arena.md)

design/user-stories/us-011-inform-and-manage-participation.md

@@ -34,6 +34,6 @@ As a **player**, I want to understand my status and control my eligibility so th
 
 ## Related
 
-- [Handle inactivity and pending selections](us-010-handle-inactivity-and-selection.md)
+- [Handle inactivity and arena vacancies](us-010-handle-inactivity-and-selection.md)
 - [Persistence model](../concepts/persistence-model.md)
 - [Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)

design/user-stories/us-012-configure-and-persist-state.md

@@ -11,8 +11,8 @@ As a **server operator**, I want configurable and durable game behavior so that
 
 ## Acceptance criteria
 
-- [x] Configuration covers ranges, durations, cooldowns, inactivity periods, candidate windows, retry intervals, effect levels and caps, mob restrictions, item materials and names, messages, timer behavior, and Vigilante arena boss balance.
-- [x] Defaults match the approved user stories, including a 50-block Tyrant range and Follower range, seven-day opt-out, 48-hour inactivity, and 24-hour candidate windows.
+- [x] Configuration covers ranges, durations, cooldowns, inactivity and maintenance intervals, effect levels and caps, mob restrictions, item materials and names, messages, timer behavior, and shared-role-arena boss balance.
+- [x] Defaults match the approved user stories, including a 50-block Tyrant range and Follower range, seven-day opt-out, 48-hour inactivity, and one-minute role maintenance.
 - [x] Invalid required configuration prevents partial plugin initialization and produces a clear server log message.
 - [x] UUID-keyed state stores lifecycle, current and pending roles, assignments, login history, participation, reign progression, purchases, choices, cooldowns, paused time, item delivery, and captured mobs; the administrator-set arena center is durable across restarts.
 - [x] Cooldowns and deadlines use UTC instants and exclude administratively paused time.
@@ -26,3 +26,4 @@ As a **server operator**, I want configurable and durable game behavior so that
 - [Persistence model](../concepts/persistence-model.md)
 - [Build, test, and release the plugin](us-013-build-test-and-release.md)
 - [Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)
+- [Claim the Tyrant role in the arena](us-020-claim-tyrant-in-arena.md)

design/user-stories/us-016-manage-vigilante-control-panel.md

@@ -42,7 +42,7 @@ Automated tests verify default and explicit command entry points, active-Vigilan
 ## Related
 
 - [Support the Vigilante and Followers](us-008-support-vigilante-and-followers.md)
-- [Handle inactivity and pending selections](us-010-handle-inactivity-and-selection.md)
+- [Handle inactivity and arena vacancies](us-010-handle-inactivity-and-selection.md)
 - [Manage a reign through the Tyrant control panel](us-015-manage-tyrant-control-panel.md)
 - [Role and class model](../concepts/role-and-class-model.md)
 - [Use bound role control items](us-017-use-bound-role-control-items.md)

design/user-stories/us-019-claim-vigilante-in-arena.md

@@ -12,8 +12,8 @@ As an **opted-in participant**, I want a visible one-player boss challenge for a
 ## Acceptance criteria
 
 - [x] An administrator can set and inspect a durable arena center, and configuration validates the arena radius and boss strength.
-- [x] The configured arena has a continuously visible particle boundary, including when no fight is active.
-- [x] A vacant Vigilante role opens the challenge after death, inactivity, relinquishment, or a new Tyrant reign, but a boss exists only while a Tyrant is active and the game is running.
+- [x] The configured arena has a continuously visible neutral boundary when no challenge is open and a blue particle boundary while the Vigilante challenge is open.
+- [x] A vacant Vigilante role opens the challenge after death, inactivity, relinquishment, or a new Tyrant reign, but only while a Tyrant is active, no Tyrant challenge is open, and the game is running.
 - [x] The challenge boss defaults to an armored, 80-health enhanced zombie, does not burn in sunlight, and remains within a default 10-block-radius arena.
 - [x] All online opted-in players are told when the role opens and receive the arena world and coordinates; opted-in players receive the same notice when they log in while it remains open, and opted-out players do not.
 - [x] Exactly one eligible opted-in non-Tyrant player may enter as challenger, including when entry is attempted by walking or teleportation.
@@ -30,6 +30,7 @@ As an **opted-in participant**, I want a visible one-player boss challenge for a
 
 - [Start, pause, and administer the game](us-001-start-pause-and-administer.md)
 - [Support the Vigilante and Followers](us-008-support-vigilante-and-followers.md)
-- [Handle inactivity and pending selections](us-010-handle-inactivity-and-selection.md)
+- [Handle inactivity and arena vacancies](us-010-handle-inactivity-and-selection.md)
 - [Configure and persist game state](us-012-configure-and-persist-state.md)
 - [Tyrant game state machine](../concepts/game-state-machine.md)
+- [Claim the Tyrant role in the arena](us-020-claim-tyrant-in-arena.md)

design/user-stories/us-020-claim-tyrant-in-arena.md

@@ -0,0 +1,30 @@
+---
+type: User Story
+title: "US-020: Claim the Tyrant role in the arena"
+description: Use the shared one-player arena to replace a Tyrant who was not defeated by another player.
+status: done
+---
+
+# US-020: Claim the Tyrant role in the arena
+
+As an **opted-in participant**, I want to earn a vacant Tyrant role through the shared boss arena so that environmental death, inactivity, and relinquishment do not assign power randomly.
+
+## Acceptance criteria
+
+- [x] A player directly credited with killing the Tyrant still becomes the new Tyrant immediately without an arena fight.
+- [x] Tyrant death without a player killer, Tyrant inactivity, and Tyrant relinquishment end the reign, clear all role-side assignments, and open the shared arena with no active or pending Tyrant.
+- [x] The shared arena opens only one role challenge at a time: a vacant Tyrant takes priority, and the Vigilante challenge can open only after a Tyrant becomes active.
+- [x] The passive arena boundary uses red particles for an open Tyrant challenge, blue particles for an open Vigilante challenge, and a neutral marker while neither role challenge is open.
+- [x] The Tyrant challenge uses the existing configured arena, boss balance, mob exclusion, one-challenger barrier, containment, reset, notification, and missing-location rules.
+- [x] An eligible opted-in participant, including the former Tyrant, may challenge for the vacant Tyrant role; an active Tyrant cannot enter any arena fight.
+- [x] Defeating the Tyrant challenge boss assigns the challenger as Tyrant with level zero, no purchases, and exactly one starting unlock choice.
+- [x] Completing the Tyrant challenge immediately permits the blue Vigilante challenge to open at the same location when the Vigilante role is vacant.
+- [x] Legacy pending Tyrant replacement state is cleared into an arena vacancy without granting a role.
+- [x] Pausing, resetting, restarting, reloading, and repeated or concurrent events cannot duplicate either role boss, challenger, barrier, or assignment.
+
+## Related
+
+- [Transfer and reset the Tyrant role](us-002-transfer-and-reset-tyrant.md)
+- [Handle inactivity and arena vacancies](us-010-handle-inactivity-and-selection.md)
+- [Claim the Vigilante role in the arena](us-019-claim-vigilante-in-arena.md)
+- [Tyrant game state machine](../concepts/game-state-machine.md)