fix(docking): retry the undock; a lost keyword left the panel black

Round 6 passed on the plug side but unplugging the cable left the laptop
panel black until it was re-docked. The journal named it: across three
undocks, two logged result=enable-timeout and one result=ok — a race, not
a logic error.

Two halves, both needed:

  - `hyprctl keyword monitor eDP-1,preferred,auto,1` is accepted (exit 0)
    while Hyprland is still tearing down the departing external, then
    silently dropped. Re-issue it on every poll for 5s and keep `monitors`
    listing the panel — not hyprctl's exit code — as the only proof.

  - The watcher fired the undock once off the removal event and marked the
    departure handled regardless (`|| true` + awaiting_lid_open=1). Since
    known_outputs had already moved, the set-changed guard never reopened
    and nothing retried, so one lost keyword cost the panel until re-dock.
    The undock is now a queued invariant driven on the 1s tick, bounded at
    6 attempts so a genuinely unenableable panel can't pin the inhibitor.

The VM harness cannot reach this race: QEMU's headless backend aborts
Hyprland if the last active output is deleted while the DRM output is
disabled, so the test must undock before removing DP-1 and never collides
the two. Noted there, and V3 queued as round 7 — unplug 5+ times, since
the old failure only hit ~2 in 3.

Verified: V2 — nix flake check --no-build; monitor-fallback.nix exit 0 in
57s; shellcheck clean. The fix itself is V3 pending.

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

agent/HARDWARE-QUEUE.md

@@ -32,7 +32,40 @@ the **T14s** (webcam case).
       nomarchy-battery-charge-limit.service` stays false, `Result=success`,
       BAT0's `charge_control_end_threshold` still matches the limit, and the
       journal has no new `start-limit-hit`/`Failed with result` lines.
-- [ ] **Docking recovery round 5 (dock/keyboard/audio hotplug, 2026-07-14)**
+- [ ] **Docking recovery round 7 (undock panel restore, 2026-07-14)** —
+      round 6 (AMD dev box, Bernardo) **passed on the plug side**: the dock
+      docked by itself, audio went straight to the monitor, and the wallpaper
+      painted on the external. One count failed: **unplugging the cable left
+      the laptop panel black**, recoverable only by re-docking. The journal
+      named the cause exactly — across three undocks, two logged
+      `transition=undock internal=eDP-1 result=enable-timeout` and one
+      `result=ok`, i.e. an intermittent race, not a logic error. Both halves
+      are fixed in the commit carrying this entry: `hyprctl keyword monitor
+      eDP-1,preferred,auto,1` is *accepted* (exit 0) while Hyprland is still
+      tearing down the departing external and then silently dropped, so the
+      transition now re-issues it on every poll for 5s rather than trusting
+      one shot; and the watcher no longer treats a failed undock as final —
+      the departure is queued and retried on the 1s tick (up to 6 attempts)
+      instead of being marked handled with `|| true`, which is what turned one
+      lost keyword into a panel dark until re-dock. **The VM harness cannot
+      reach this** (`tools/monitor-fallback.nix`: QEMU's headless backend
+      aborts Hyprland if the last active output is deleted while the DRM
+      output is disabled, so the test must undock *before* removing DP-1 and
+      never collides the two) — hardware is the only place it can be proven.
+      **Re-check:** relogin (mandatory — see below), dock, then unplug the
+      cable **at least five times**, since the old failure only hit ~2 of 3.
+      **Pass:** the panel comes back every single time with workspaces intact,
+      and `journalctl --user -t nomarchy-display-transition -t
+      nomarchy-display-watch --since '-10 min'` shows a
+      `transition=undock result=ok attempts=N` for each undock and **never**
+      `result=gave-up`. `attempts=2` or more is the retry doing its job and is
+      a pass; `gave-up` means the panel could not be enabled at all and is a
+      different fault — capture the artifacts listed in round 4 before
+      changing state.
+- [ ] **Docking recovery round 5/6 (keyboard + headphone-jack counts,
+      2026-07-14)** — round 6 confirmed the dock/audio/wallpaper counts
+      below; the **keyboard-prompts-exactly-once** and **headphone
+      plug/unplug** counts were not reported either way and still need a run.
       — round 4 was run on the AMD dev box and **failed on four counts**
       (Bernardo): no wallpaper on the external monitor, no automatic dock
       mode (System › Display had to be used by hand), audio staying on the

agent/JOURNAL.md

@@ -19,6 +19,34 @@ Template:
 
 ---
 
+## 2026-07-14 — docking round 6: undock left the laptop panel black (this commit)
+- **Task:** HARDWARE-QUEUE docking round 6 result (Bernardo, AMD dev box).
+  Plug side all passed (auto-dock, audio to the monitor, wallpaper on the
+  external); unplugging left the panel black until re-docked.
+- **Did:** Bernardo's journal was decisive — 3 undocks, 2×
+  `result=enable-timeout` + 1× `result=ok`, so an intermittent race. Two
+  fixes in modules/home/hyprland.nix: (1) the undock `hyprctl keyword monitor
+  eDP-1,preferred,auto,1` exits 0 but is dropped when it lands mid-teardown
+  of the departing external — now re-issued every poll for 5s, with
+  `monitors` listing the panel as the only proof; (2) the watcher marked the
+  departure handled via `"$TRANSITION" undock … || true` + `awaiting_lid_open=1`
+  and `known_outputs` had already moved, so nothing ever retried — one lost
+  keyword = a dark panel. The undock is now a queued invariant driven on the
+  1s tick (6 attempts, then `result=gave-up`).
+- **Verified:** V2 — `nix flake check --no-build` all checks passed;
+  `nix build --impure -f tools/monitor-fallback.nix` exit 0 in 57s (reaches
+  the final `lid-open transition` checkpoint); shellcheck clean on both
+  generated scripts (the lone SC2125 is pre-existing + intentional).
+  **Honest limit:** the harness CANNOT reach this race — QEMU's headless
+  backend aborts Hyprland if the last active output is deleted while the DRM
+  output is disabled, so it must undock before removing DP-1 and never
+  collides the two. The fix itself is **V3 pending**; comment added at
+  tools/monitor-fallback.nix so a reader doesn't mistake a pass for coverage.
+- **Pending:** V3 → HARDWARE-QUEUE round 7 (unplug ≥5×; old failure was only
+  ~2 in 3). Round 5/6's keyboard-prompt + headphone-jack counts were never
+  reported either way — split into their own entry, still unverified.
+- **Next suggestion:** wait on round 7 before touching the dock path again.
+
 ## 2026-07-13 — #99 live-seed git-init; theme-switch failure filed as #113 (this commit)
 - **Task:** BACKLOG #99 — false "theme-state.json NOT git-tracked" doctor/
   Waybar warning in the live session; resolve the held question from Fable.