Bind BirdMessenger sends and deliveries to character sessions

[ryanbarlow97]

Bind mailbox menus and delayed letter writes to the originating character session and player connection. A character switch returns unsent letters to the outgoing inventory, rejects stale picker callbacks, and leaves undelivered pending letters queued for their stored owner and character.

• Replace the legacy activation listener with shared TLibs start/end events and require ready identity for sending and delivery. Keep RPCharacters' opted-in mail directory, textures and flight destinations.
• Drain pending mail one letter at a time with a session check between deliveries. Preserve existing files, character ID spelling and in-flight delivery across activations; reject malformed IDs and owner mismatches without consuming their mail.
• Detach confirmed sends before callbacks, retain failed refunds independently of replacement sessions, and prevent new sessions during shutdown. Once mail is accepted or refunded, later scheduling/notification errors cannot also create a sender refund.
• Pin TLibs 2.3.0 and RPCharacters 2.16.0; fail startup cleanly with an older TLibs API.

Validation: Java 21 mvn clean verify passed 202 tests with no failures or skips and 100% line coverage (1,374 lines). Runtime JAR validation passed. Independent Astra review findings were fixed and re-reviewed. Regression coverage includes A → B → A, reconnects, provider changes, reentrant menu replacement, interrupted pending delivery, storage conflicts and post-accept failures.

Docs: TF-Minecraft/Docs#168

The full pinned local Paper integration run follows the remaining Stage 2 consumer migrations. No server deployment is included.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: ff42d993-9d05-4e8d-b6f0-7c7bcbf6042e

---

📥 Commits

Reviewing files that changed from the base of the PR and between 48d6e96 and 52ec299.

---

📒 Files selected for processing (27)

• pom.xml
• src/main/java/net/tfminecraft/birdmessenger/BirdMessenger.java
• src/main/java/net/tfminecraft/birdmessenger/gui/CharacterPickerGui.java
• src/main/java/net/tfminecraft/birdmessenger/gui/LetterGui.java
• src/main/java/net/tfminecraft/birdmessenger/letters/LetterListener.java
• src/main/java/net/tfminecraft/birdmessenger/listener/CharacterActivatedListener.java
• src/main/java/net/tfminecraft/birdmessenger/listener/CoopListener.java
• src/main/java/net/tfminecraft/birdmessenger/listener/GuiListener.java
• src/main/java/net/tfminecraft/birdmessenger/listener/PlayerSessionListener.java
• src/main/java/net/tfminecraft/birdmessenger/listener/RpCharactersHook.java
• src/main/java/net/tfminecraft/birdmessenger/mail/MailDelivery.java
• src/main/java/net/tfminecraft/birdmessenger/mail/MailService.java
• src/main/java/net/tfminecraft/birdmessenger/mail/MailStore.java
• src/main/java/net/tfminecraft/birdmessenger/session/SendSession.java
• src/main/java/net/tfminecraft/birdmessenger/session/SendSessionManager.java
• src/test/java/net/tfminecraft/birdmessenger/PickerOpenTest.java
• src/test/java/net/tfminecraft/birdmessenger/PluginLifecycleCoverageTest.java
• src/test/java/net/tfminecraft/birdmessenger/gui/GuiPresentationCoverageTest.java
• src/test/java/net/tfminecraft/birdmessenger/letters/LetterListenerTest.java
• src/test/java/net/tfminecraft/birdmessenger/listener/GuiListenerCoverageTest.java
• src/test/java/net/tfminecraft/birdmessenger/listener/PlayerSessionListenerTest.java
• src/test/java/net/tfminecraft/birdmessenger/listener/RpCharactersHookTest.java
• src/test/java/net/tfminecraft/birdmessenger/mail/DeliverySessionCoverageTest.java
• src/test/java/net/tfminecraft/birdmessenger/mail/MailRecipientOptOutTest.java
• src/test/java/net/tfminecraft/birdmessenger/mail/MailServiceCoverageTest.java
• src/test/java/net/tfminecraft/birdmessenger/mail/MailStoreCoverageTest.java
• src/test/java/net/tfminecraft/birdmessenger/session/SendSessionManagerTest.java

---

💤 Files with no reviewable changes (3)

• src/test/java/net/tfminecraft/birdmessenger/listener/RpCharactersHookTest.java
• src/main/java/net/tfminecraft/birdmessenger/listener/CharacterActivatedListener.java
• src/main/java/net/tfminecraft/birdmessenger/listener/RpCharactersHook.java

---

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

---

📝 Summary

Summary by CodeRabbit

• New Features
  • Letter writing and sending now follows the player’s active character, keeping letters and refunds associated with the correct character when sessions change.
  • Mail for unavailable recipients is queued for delivery when they next become available.
• Bug Fixes
  • Stale character sessions and reconnects no longer allow delayed letter edits or sends to affect the wrong session.
  • Letters and staged items are retained for later return if they cannot be returned immediately.

Walkthrough

The change updates character-library versions and moves send sessions, GUI operations, mail delivery and deferred letter updates to character-session-aware checks. It adds pending-mail polling and return retries, and removes the RPCharacters activation hook.

Changes

Character-session messaging

Layer / File(s)	Summary
Character-session lifecycle pom.xml, src/main/java/net/tfminecraft/birdmessenger/BirdMessenger.java, src/main/java/net/tfminecraft/birdmessenger/listener/PlayerSessionListener.java, src/main/java/net/tfminecraft/birdmessenger/listener/CharacterActivatedListener.java, src/main/java/net/tfminecraft/birdmessenger/listener/RpCharactersHook.java, src/main/java/net/tfminecraft/birdmessenger/session/*, src/test/java/net/tfminecraft/birdmessenger/session/*, src/test/java/net/tfminecraft/birdmessenger/listener/PlayerSessionListenerTest.java, src/test/java/net/tfminecraft/birdmessenger/PluginLifecycleCoverageTest.java	The dependency versions change to rpcharacters 2.16.0 and tlibs 2.3.0. Plugin setup checks character API linkage, registers session event handling and closes the session manager on shutdown. Send sessions bind a player to a character session and track staged items and queued returns.
Session-bound letter and picker GUIs src/main/java/net/tfminecraft/birdmessenger/BirdMessenger.java, src/main/java/net/tfminecraft/birdmessenger/gui/*, src/main/java/net/tfminecraft/birdmessenger/listener/CoopListener.java, src/main/java/net/tfminecraft/birdmessenger/listener/GuiListener.java, src/test/java/net/tfminecraft/birdmessenger/PickerOpenTest.java, src/test/java/net/tfminecraft/birdmessenger/gui/GuiPresentationCoverageTest.java, src/test/java/net/tfminecraft/birdmessenger/listener/GuiListenerCoverageTest.java	Letter and picker GUIs retain their send session. Opening, refresh, close and confirmation paths validate that session. Confirmation detaches the letter before calling mail service and retains the letter for return if the hand-off throws.
Session-aware mail and pending storage src/main/java/net/tfminecraft/birdmessenger/mail/*, src/test/java/net/tfminecraft/birdmessenger/mail/*	Mail sending and pending delivery now use CharacterSession and CharacterRef. Pending mail is polled one item at a time with owner matching. Mail that cannot be delivered is stored as pending before its in-flight entry is removed.
Session-aware letter edits src/main/java/net/tfminecraft/birdmessenger/letters/LetterListener.java, src/test/java/net/tfminecraft/birdmessenger/letters/LetterListenerTest.java	Book edit, sign and open events capture the current character session. Deferred item updates check that the captured session and player connection remain current.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant GuiListener
  participant MailService
  participant MailStore
  participant MailDelivery
  GuiListener->>MailService: trySend with origin CharacterSession
  MailService->>MailStore: store accepted mail as in-flight
  MailService->>MailDelivery: schedule flight delivery
  MailDelivery->>MailStore: store undeliverable mail as pending

Loading

---

Merge Risk: ⚪ Minimal · up to 52ec2

Mailbox sends and deliveries are now tied to the current character session. Unsent letters are returned or queued for the original character. The supplied evidence shows no concrete merge-blocking defect. Confirm that the pinned library versions resolve in the build repositories.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}