feat(stealth): mask identities and notify admins on login

design/index.md

@@ -4,7 +4,9 @@ okf_version: "0.1"
 
 # Spigot Stealth Design
 
-Spigot Stealth rewards players who spend time under invisibility effects from potions they drink, then lets unlocked players conceal their identity for a later session.
+Spigot Stealth rewards players who spend time under invisibility effects from potions they drink, then lets unlocked players conceal their identity for a later session. [Session concealment](user-stories/us-002-rejoin-without-visible-identity.md) includes command-suggestion filtering and scrambled message and overhead names.
+
+[Administration](user-stories/us-004-administer-player-stealth.md) provides private concealed-player counts at login and command-based inspection.
 
 ## Explore
 

design/log.md

@@ -1,5 +1,11 @@
 # Spigot Stealth Design Log
 
+## 2026-09-06
+
+- **Completion**: Extended US-004 with permission-gated private concealed-player counts for joining admins and arrival notices for online admins, including command hints, zero-count silence, and no duplicate notice for concealed admins. Verified all 70 tests, the JAR build, and OKF validation; not deployed or live-server tested.
+
+- **Completion**: Extended US-002 with concealed-username suggestion filtering, scrambled default chat and vanilla message/advancement names, scrambled overhead tags, and display-name restoration. Verified 65 automated tests, the Gradle JAR build, and OKF validation; live-server compatibility remains untested and custom chat/scoreboard integrations are outside this slice.
+
 ## 2026-09-05
 
 - **Fix**: Reworked US-002 server-list filtering for Purpur's native `NameAndId` samples by filtering names through Bukkit, limiting ProtocolLib to guarded count adjustment, and rate-limiting compatibility warnings; verified the complete Gradle build and OKF bundle.

design/user-stories/index.md

@@ -1,8 +1,8 @@
 # Spigot Stealth User Stories
 
 1. [US-001: Accumulate invisibility time and unlock stealth](us-001-accumulate-invisibility-and-unlock.md) - Earn stealth by spending eight hours under invisibility effects from directly consumed potions.
-2. [US-002: Rejoin without a visible identity](us-002-rejoin-without-visible-identity.md) - Turn a qualifying invisible disconnect into one concealed online session.
+2. [US-002: Rejoin without a visible identity](us-002-rejoin-without-visible-identity.md) - Turn a qualifying invisible disconnect into one concealed online session with filtered name suggestions and scrambled message and overhead names.
 3. [US-003: Check personal stealth progress](us-003-check-personal-progress.md) - View accumulated time, remaining time, and unlock status.
-4. [US-004: Inspect and manage player stealth](us-004-administer-player-stealth.md) - Inspect and modify online or offline progression and find concealed players.
+4. [US-004: Inspect and manage player stealth](us-004-administer-player-stealth.md) - Inspect and modify online or offline progression, find concealed players, and receive private login count notices.
 5. [US-005: Configure and persist stealth progression](us-005-configure-and-persist-progression.md) - Keep progression durable and operator-configurable.
 6. [US-006: Build, test, and release the plugin](us-006-build-test-and-release.md) - Provide repeatable Gradle builds and Gitea delivery.

design/user-stories/us-002-rejoin-without-visible-identity.md

@@ -29,7 +29,11 @@ As an **unlocked player**, I want to disconnect while invisibility from a potion
 - [x] When the sleep-count policy is `include`, concealed players count normally; ordinary players are never modified by either policy.
 - [x] A player's previous sleeping-ignore state is restored when concealment ends, the player disconnects or is reset, the policy changes to `include`, or the plugin disables.
 - [x] Policy changes apply immediately to currently concealed players.
-- [x] Throughout the concealed session, no overhead name tag identifies the player to any other player, including administrators.
+- [x] Throughout the concealed session, the overhead name is rendered as scrambled magic text, including for administrators, while the physical character stays visible.
+- [x] Concealed usernames are excluded from outgoing command suggestions, including `/msg`, `/tell`, and `/w`; manually addressing a known username remains possible.
+- [x] Default chat display names and vanilla private-message and advancement name components are scrambled without changing message content or signed chat bodies.
+- [x] Masked message name components do not expose the original identity through hover or click actions.
+- [x] Previous display names and ordinary suggestions return when concealment ends; ordinary players remain unaffected.
 - [x] The concealed player's physical character remains visible in the world and retains ordinary movement, interaction, combat, and permission behavior.
 - [x] The concealed player receives a private message explaining that stealth is active for the session.
 - [x] Concealment lasts until the player disconnects and is handled predictably across death and plugin reload or disable events.
@@ -41,6 +45,16 @@ As an **unlocked player**, I want to disconnect while invisibility from a potion
 
 Automated tests verify unlocked and locked disconnect transitions, ordinary-disconnect clearing, one-login consumption, concealed join and quit announcement suppression, preservation of ordinary announcements, private activation messaging, ordinary-login presentation, tab removal for existing and new observers, overhead-name suppression, active concealed-session tracking, ProtocolLib-independent native player-sample filtering, guarded public server-list count adjustment, nonnegative counts, unchanged maximum capacity, default sleep-count exclusion, immediate policy changes, restoration of prior sleeping-ignore state, and the absence of entity-hiding calls. ProtocolLib is declared as a required dependency, prepared state round trips through YAML, and `./gradlew clean check jar` passes.
 
+Identity masking verification (2026-09-06): `./gradlew --offline clean check jar` passed all 65 tests and OKF validation. Tests cover semantic name slots, preserved message content, stripped identifying actions, reflected suggestion entries and chat-bound records, safe packet failure handling, immutable name snapshots, overhead formatting, and display-name restoration after repeated concealment. Presentation tests first failed to compile against the missing snapshot API, then passed after implementation. These are automated unit checks, not a live-client smoke test.
+
+## Identity masking scope
+
+Masking applies to active concealed sessions, not every potion effect. Outgoing username suggestions are filtered across commands; entering a known username manually still works. Default Bukkit chat uses a temporary scrambled `Anonymous` display name. Vanilla translated announcements and chat-type bound names are masked at the packet boundary without editing signed message bodies. The overhead tag uses scoreboard magic formatting on the profile name, not a profile rename; this is visual concealment, not anonymity against modified clients.
+
+Custom chat formats that ignore Bukkit display names, nicknames, custom scoreboards, and third-party messaging plugins may need dedicated integration. Unsupported packet layouts retain the original packet and emit one warning per packet type rather than interrupting chat delivery. Live-server/client compatibility still requires a smoke test, particularly after Minecraft or ProtocolLib upgrades.
+
+Implementation: [identity presentation](../../src/main/java/games/dmg/spigotstealth/BukkitIdentityPresentation.java), [packet listener](../../src/main/java/games/dmg/spigotstealth/ProtocolLibIdentityMaskingListener.java), and [semantic name masking](../../src/main/java/games/dmg/spigotstealth/StealthChatMasker.java).
+
 ## Related
 
 - [Accumulate invisibility time and unlock stealth](us-001-accumulate-invisibility-and-unlock.md)

design/user-stories/us-004-administer-player-stealth.md

@@ -19,7 +19,12 @@ As a **server administrator**, I want to inspect and correct player stealth stat
 - [x] `/stealthadmin reset <player|uuid> confirm` clears accumulated time, unlock ownership, prepared-login state, and current concealment for an online or known offline player.
 - [x] Reset requires explicit confirmation and safely restores an online concealed player to ordinary identity presentation.
 - [x] `/stealthadmin list` lists every currently online concealed player and clearly reports when there are none.
-- [x] Concealed players remain absent from administrators' ordinary tab lists and retain hidden overhead name tags; the admin command is the supported discovery mechanism.
+- [x] Concealed players remain absent from administrators' ordinary tab lists and retain scrambled overhead names; the admin command is the supported discovery mechanism.
+- [x] An administrator joining while concealed players are online receives a private count and a hint to use `/stealthadmin list`.
+- [x] When a concealed player joins, online administrators receive a private arrival notice, the updated concealed-player count, and the command hint.
+- [x] Notifications require `spigotstealth.admin`; ordinary players receive no administrative notice.
+- [x] Counts include the newly joined concealed player, and a joining concealed administrator receives only one administrative notification.
+- [x] An administrator joining when no concealed players are online receives no notification.
 - [x] Commands clearly reject unknown, ambiguous, malformed, or otherwise invalid targets without creating unintended player records.
 - [x] Administrative inspection and modification require an operator-default administrative permission.
 - [x] State-changing operations persist before success is reported and are safe under retries.
@@ -38,6 +43,10 @@ As a **server administrator**, I want to inspect and correct player stealth stat
 
 Automated tests verify exact offline name and UUID resolution, ambiguous and unknown rejection without record creation, complete status output, idempotent grants and notification, complete resets with presentation cleanup, online concealed-player filtering, online and offline unlocked-player listing, contextual permission-gated completion, durable sleep-count status and policy changes, immediate policy refresh, confirmation and permission gates, persisted-before-success replies, and audit records. The complete `./gradlew clean check jar` lifecycle passes.
 
+Login notice verification (2026-09-06): `./gradlew --offline clean check jar` passed all 70 tests and OKF validation. New tests first failed against the absent listener, then passed after implementation. Tests cover permission gates, zero-count silence, singular/plural counts, concealed-admin deduplication, ordinary-join silence for existing admins, and a prepared-login transition followed by an accurate administrative notice. Live-server verification remains pending.
+
+Implementation: [admin join listener](../../src/main/java/games/dmg/spigotstealth/StealthAdminJoinListener.java), registered at `MONITOR` after the session listener's `HIGHEST` login transition. Notices expose only counts; names remain available through `/stealthadmin list`.
+
 ## Related
 
 - [Rejoin without a visible identity](us-002-rejoin-without-visible-identity.md)