fix(death): address review findings

Three of the four findings were valid:

1. getNearest used WorldPoint.distanceTo, which returns Integer.MAX_VALUE across
   planes. Every entrance is on plane 0, so a player on any upper floor scored
   MAX_VALUE for all eight and min() silently returned the first constant —
   Lumbridge — however far away it was. Switched to distanceTo2D.

2. Two Javadoc blocks were orphaned when the item-reader methods were inserted
   ahead of the methods they described: the grave "claims the half that costs
   nothing" block landed on getGraveFreeItems, and the detailed reclaimAll block
   (spending-limit rationale and @return) landed on getDeathsOfficeItems. Both
   moved to the methods they document; no implementation change.

3. The Death's Office example in the guide called reclaimAll() unconditionally
   under a comment about pricing the office first — stale since the fee estimator
   was removed. It now reads the contents, leaves the decision to the caller, and
   shows closeInterfaces() as the free way to decline.

The fourth — make reclaimItems resolve container and quantity buttons per retrieval
variant, mirroring reclaimAll — is not implementable as described. Confirmed against
the game cache (iftypes): death_office (669) has 1/5/x/all/takeall, while
gravestone_retrieval (602) has no quantity controls at all, only button /
button_bank / discard. There is nothing to resolve to. The real defect underneath it
was that reclaimItems read the DeathOffice container unconditionally even though
isDeathsOfficeOpen accepts either variant, so on 602 it would read an empty container
and report "took nothing". It now detects the variant and fails loudly, pointing the
caller at reclaimAll(). Both interfaces' component lists are documented in the guide.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: infuse21

docs/entity-guides/death.md

@@ -17,10 +17,15 @@ if (Rs2Death.hasDeathToHandle()) {
 // opt in to the Death's Office trip as well, if the script wants expired items back
 Rs2Death.recoverItems(config.deathBudget(), config.useDeathsOffice());
 
-// or price the office yourself before committing — the trip is free, only the reclaim costs
+// or inspect before committing — walking there is free, only the reclaim costs
 if (Rs2Death.walkToDeathsOffice() && Rs2Death.enterDeathsOffice() && Rs2Death.openDeathsOffice()) {
-    Rs2Death.reclaimAll();        // no cap is possible — see rule 11
-    Rs2Death.closeInterfaces();   // or inspect first and close to decline without paying
+    List<Rs2ItemModel> waiting = Rs2Death.getDeathsOfficeItems();
+
+    if (worthReclaiming(waiting)) {          // the script's own call — see rule 11, no cap is possible
+        Rs2Death.reclaimAll();               // takes everything, at whatever it costs
+        // or: Rs2Death.reclaimItems(i -> i.getName().contains("rune"));
+    }
+    Rs2Death.closeInterfaces();              // declining is free; Death keeps them indefinitely
 }
 ```
 
@@ -353,6 +358,18 @@ What to use instead:
   reclaim costs. A script that insists on its own cap can price the contents itself and owns that
   assumption.
 
+**Two different retrieval interfaces exist, and only one supports selective taking.** Confirmed against
+the game cache (`iftypes`):
+
+| Group | Components | Selective? |
+|---|---|---|
+| `death_office` (669) | `items`, **`1` `5` `x` `all`**, `takeall`, `info` | yes — select a slot, then a quantity |
+| `gravestone_retrieval` (602) | `items`, `button`, `button_bank`, `discard`, `fee`, `info` | **no quantity controls at all** |
+
+`isDeathsOfficeOpen()` accepts either, so `reclaimItems(filter)` checks which one is actually up and
+refuses on 602 rather than reading the wrong container and reporting "took nothing". `reclaimAll()`
+handles both, clicking `takeall` or `button` as appropriate.
+
 **Where this applies:** `Rs2Death.reclaimAll`, `Rs2Death.recoverItems`.
 
 ## 12. Death's Office needs the entrance object, then a dialogue — not an NPC click

runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/death/DeathsOfficeLocation.java

@@ -55,8 +55,11 @@ public static DeathsOfficeLocation getNearest() {
 
     public static DeathsOfficeLocation getNearest(WorldPoint from) {
         if (from == null) return null;
+        // distanceTo2D, not distanceTo: the latter returns Integer.MAX_VALUE across planes, and every
+        // entrance is on plane 0. A player upstairs would score MAX_VALUE for all of them, so min()
+        // would silently return the first constant (Lumbridge) however far away it is.
         return Arrays.stream(values())
-                .min(Comparator.comparingInt(location -> location.entrance.distanceTo(from)))
+                .min(Comparator.comparingInt(location -> location.entrance.distanceTo2D(from)))
                 .orElse(null);
     }
 }

runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/death/Rs2Death.java

@@ -456,9 +456,6 @@ public static int getGraveFee() {
         return parseFee(Rs2Widget.getWidget(InterfaceID.GravestoneGeneric.FEE));
     }
 
-    /**
-     * Claims the half of the grave that costs nothing. Items behind a fee are untouched and stay put.
-     */
     /**
      * The items in the grave's free half — everything that costs nothing to reclaim. Requires the grave
      * interface to be open ({@link #openGrave()}).
@@ -476,8 +473,8 @@ public static List<Rs2ItemModel> getGravePaidItems() {
     }
 
     /**
-     * Takes <b>everything</b> in the free half. Use {@link #lootGraveItems(Predicate)} to take only some
-     * of it.
+     * Takes <b>everything</b> in the free half; items behind the fee are untouched and stay put. Use
+     * {@link #lootGraveItems(Predicate)} to take only some of it.
      */
     public static boolean lootGraveFreeItems() {
         if (!isGraveOpen()) return false;
@@ -682,21 +679,6 @@ private static void advanceReclaimDialogue() {
         }
     }
 
-    /**
-     * Reclaims everything Death is holding, into the inventory. Death's Office keeps items
-     * indefinitely, so a partial reclaim caused by a full inventory is safe to resume later.
-     * <p>
-     * <b>There is deliberately no spending limit, because one is not possible.</b> The fee is never on
-     * screen before it is charged — verified live, {@code INFO} reads "Select an item to retrieve."
-     * whether the office is empty or holding items, the {@code 1}/{@code 5}/{@code X}/{@code All}
-     * buttons stay hidden until an item is selected, and {@code Take-All} never selects. Any cap here
-     * would be fiction.
-     * <p>
-     * Calling this authorises an unbounded charge against Death's Coffer, and the bank after that.
-     * Death's Office holds items indefinitely, so declining to call it is always a safe alternative.
-     *
-     * @return {@code true} once the retrieval interface has closed with nothing left to collect.
-     */
     /**
      * The items Death is currently holding. Requires the retrieval interface to be open
      * ({@link #openDeathsOffice()}) — the office cannot be inspected from afar, though walking there and
@@ -723,6 +705,17 @@ public static List<Rs2ItemModel> getDeathsOfficeItems() {
     public static int reclaimItems(Predicate<Rs2ItemModel> filter) {
         if (!isDeathsOfficeOpen()) return 0;
 
+        // Selective reclaim is DeathOffice-only. isDeathsOfficeOpen also accepts the
+        // GravestoneRetrieval variant, but that interface has no per-quantity controls at all — its
+        // components are BUTTON / BUTTON_BANK / DISCARD, with no 1/5/X/All — so the select-then-take
+        // flow below has nothing to click there. Fail loudly rather than reading the wrong container
+        // and silently reporting "took nothing".
+        if (!Rs2Widget.isWidgetVisible(InterfaceID.DeathOffice.ITEMS_CONTAINER)) {
+            log.warn("Selective reclaim needs the Death's Office interface; the retrieval-service "
+                    + "variant has no quantity controls. Use reclaimAll() instead.");
+            return 0;
+        }
+
         List<Rs2ItemModel> items = getDeathsOfficeItems();
         int taken = 0;
         for (int i = items.size() - 1; i >= 0; i--) {
@@ -748,9 +741,21 @@ public static int reclaimItems(Predicate<Rs2ItemModel> filter) {
     }
 
     /**
-     * Reclaims <b>everything</b> Death is holding. Use {@link #reclaimItems(Predicate)} to take only
-     * some of it.
+     * Reclaims everything Death is holding, into the inventory. Death's Office keeps items
+     * indefinitely, so a partial reclaim caused by a full inventory is safe to resume later.
+     * <p>
+     * <b>There is deliberately no spending limit, because one is not possible.</b> The fee is never on
+     * screen before it is charged — verified live, {@code INFO} reads "Select an item to retrieve."
+     * whether the office is empty or holding items, the {@code 1}/{@code 5}/{@code X}/{@code All}
+     * buttons stay hidden until an item is selected, and {@code Take-All} never selects. Any cap here
+     * would be fiction.
+     * <p>
+     * Calling this authorises an unbounded charge against Death's Coffer, and the bank after that.
+     * Death's Office holds items indefinitely, so declining to call it is always a safe alternative.
+     *
+     * @return {@code true} once the retrieval interface has closed with nothing left to collect.
      */
+
     public static boolean reclaimAll() {
         if (!isDeathsOfficeOpen()) return false;