I have a small macOS menu-bar utility that turns individual monitors off and back on. One morning its header said “Active displays: 2” and the menu underneath listed three: Display 1, Display 2, Display 3. I have two monitors.
Asking the system directly
The first step was to stop reading my own UI and query the display system itself. Only two displays were online and active, with IDs 1 and 3. The header was right. The list was wrong. The two were coming from different places.
Count from now, list from memory
The count was computed from the live display state. The list was built from a stored history: every display ID the app had ever observed was saved in the user defaults, and the menu merged that history with the current displays.
That design assumes a display ID names a monitor. It doesn't. The IDs the display system hands out can be reassigned depending on connection order and session, so an ID seen last week can now belong to a different monitor, or to none. The phantom “Display 2” was an old ID for a monitor that was now reporting under a different one — an offline ghost of a screen that was sitting right there.
Keeping less
The fix wasn't to filter the ghosts better; it was to stop remembering everything. I cleared the history and changed what is stored: only displays that were switched off deliberately through the app are kept, as candidates for reconnection. When a candidate reappears, it is removed automatically, matched either by its ID or by a hardware identity (vendor, model, serial), since the ID alone is exactly the thing that can't be trusted.
A remembered list should be a list of things I need to remember, not a log of everything I have ever seen.
What I can and can't say about the trigger
There was a possible cause. Shortly before, the 32-inch monitor had been drawing the right part of its screen clipped onto the left side. I unplugged and replugged the cable, which fixed it, and I did nothing else. A reconnection is exactly the sort of event that makes the system re-enumerate displays, so the theory is that the re-enumeration exposed a bug that had been waiting.
The evidence is thinner than the story. A screenshot of the menu from before the fix showed the labels attached to Display 2 and Display 3 — so I cannot claim the 32-inch monitor moved from ID 2 to ID 3. I took no snapshot before the cable was touched. The theory doesn't contradict anything I saw, and that is all it does. I left it as a hypothesis in the notes and set up the next check: use the off-and-keep flow for real and watch whether a display I turned off stays as a candidate and then disappears after reconnecting.