docs(window-switcher): focusHistoryID is not on HyprlandToplevel

Implementing the model found it. The property reads undefined, so the
planned sort compared NaN and silently did nothing, leaving the list in
arbitrary tracker order while looking entirely plausible. It is on
lastIpcObject instead.

Carried into the plan's later tasks so the grid does not reintroduce the
bare property, and into the notes that Task 6 puts in AGENTS.md, since a
sort that quietly does nothing is the kind of wrong answer this repo's
notes exist to prevent.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SYg4wYHq5XNbiVmMeKRb1S

1 files changed, 12 insertions, 2 deletions

diff --git a/docs/superpowers/plans/2026-09-12-window-switcher.md b/docs/superpowers/plans/2026-09-12-window-switcher.md
index f9cc6ef..839e26e 100644
--- a/docs/superpowers/plans/2026-09-12-window-switcher.md
+++ b/docs/superpowers/plans/2026-09-12-window-switcher.md
@@ -281,11 +281,19 @@ Singleton {
             if (!ws || String(ws.name).startsWith("special:")) continue;
             out.push(t);
         }
-        // Lowest focusHistoryID is the most recently used.
-        out.sort((a, b) => a.focusHistoryID - b.focusHistoryID);
+        // Lowest focusHistoryID is the most recently used. HyprlandToplevel
+        // does not expose it as a property, only inside the raw hyprctl
+        // object, where a missing one sorts last rather than as 0.
+        out.sort((a, b) => root.focusOrder(a) - root.focusOrder(b));
         return out;
     }
 
+    function focusOrder(toplevel) {
+        const o = toplevel.lastIpcObject;
+        const n = o ? Number(o.focusHistoryID) : NaN;
+        return isNaN(n) ? Number.MAX_SAFE_INTEGER : n;
+    }
+
     // Dispatch arguments are evaluated as Lua on Hyprland 0.56.2, so the
     // documented-looking `focuswindow address:0x...` is a syntax error that
     // fails silently. This form is the one that works.
@@ -801,6 +809,7 @@ Follow `mail-overview/README.md` in shape: what it is, an ASCII sketch of the la
 - Dispatch arguments are Lua on Hyprland 0.56.2, so `dispatch focuswindow address:0x...` is a syntax error that fails silently, and `hl.dsp.focus({ window = "address:0x..." })` is the form that works.
 - `HyprlandToplevel.address` has no `0x` prefix; dispatches need one.
 - `Hyprland.toplevels` reads 0 until `refreshToplevels()` is called.
+- `HyprlandToplevel` has no `focusHistoryID`; it is on `lastIpcObject`. A sort on the missing property compares `NaN` and quietly does nothing.
 - A card is a fixed 16:10 box with the preview fitted, because DP-3 is rotated and its windows are portrait while DP-1's are near 21:9.
 - Focus alone raises a stacked window on a `monocle` workspace, tested on workspace 1, so no `alterzorder` and no batch sequence are needed.
 
@@ -815,6 +824,7 @@ AGENTS.md carries the per-component notes that generalise. Add, in the style of
 - **Hyprland dispatch arguments are Lua.** `dispatch focuswindow address:0x...` is a syntax error, not a command, and it fails silently unless stderr is read. The working form is `dispatch hl.dsp.focus({ window = "address:0x..." })`. This is why `hypr-windows.sh` looks the way it does.
 - **`HyprlandToplevel.address` omits the `0x`** that `hyprctl clients` reports and that dispatches require.
 - **`Hyprland.toplevels` is empty until `refreshToplevels()`.**
+- **`HyprlandToplevel` has no `focusHistoryID` property.** It reads `undefined`, so a sort on it compares `NaN` and silently does nothing, leaving a plausible-looking list in arbitrary order. It lives on `lastIpcObject` instead.
 
 Also update the component list at the top of AGENTS.md to five, and note in the Blur section that `window-switcher` has its own namespace and layer rule.