refactor(display): extract the shared display-transition + keyboard tools (#150)

The full nomarchy-display-transition (dock/undock/enable — logging, the
lid-inhibitor gate, restore_keyboards, the failure dump) and the
nomarchy-keyboard-layout helper it calls move out of hyprland.nix into
leaf files (modules/home/display-transition.nix, keyboard-tool.nix),
imported by both hyprland.nix and idle.nix.

This kills the lossy ~22-line mini idle.nix carried under the same binary
name to dodge a circular import. The hypridle wake path (after_sleep /
DPMS on-resume) now runs the real undock — restore_keyboards after a
reload and the evidence dump on enable-failure — instead of a bare
keyword+reload, and the two copies can no longer drift.

Behaviour on the hyprland side is unchanged: the built
nomarchy-display-transition and nomarchy-keyboard-layout have
byte-identical store paths on HEAD vs this change (verbatim extraction).

Verify: all four files parse; home activationPackage + system toplevel
build; checks.docking-ux green (bash -n + safety-feature greps on the
extracted scripts). The tools/monitor-fallback.nix dock harness is red on
main already (the #148 reload-mid-dock assertion — identical failure on
clean HEAD; filed BACKLOG #154), so it could not gate this. The idle
wake-path behaviour change (full undock, incl. dock-intent clearing) is
V3 pending: on-hardware suspend/resume + zero-output rescue queued in
HARDWARE-QUEUE.

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

agent/BACKLOG.md

@@ -175,24 +175,26 @@ If that count is zero over a few weeks post-linger, **close this unbuilt**. If i
 is not, the upstream issue has sat ten months on vaxerski's "that will cause a
 segfault no?" and a reproducer would be worth more than a local guard.
 
-### 150. Extract the display-transition tool — idle.nix carries a lossy copy under the same name
+### 154. `[watch]` `tools/monitor-fallback.nix` is red on `main` at the #148 reload-mid-dock assertion
 
-Found by the 2026-07-17 structural audit. `modules/home/idle.nix:23-53` defines
+Found while verifying #150 (2026-07-20): the dock/undock VM harness fails at
-`miniTransition`, a ~22-line `writeShellScriptBin` named
+the `enforce_dock_intent` step — after a lid-closed `hyprctl reload` it waits
-**`nomarchy-display-transition`** — the same binary name as the real ~175-line
+15s (generated `<string>:75`) for the watcher to re-disable `Virtual-1` and
-tool in `modules/home/hyprland.nix:136-310` — implementing only
+times out; the panel is never re-disabled and `action=re-dock` is never
-`undock|enable`, with none of the full tool's safety: no logging, no
+logged. **Confirmed pre-existing:** a clean-HEAD worktree run
-lid-inhibitor gate, no `restore_keyboards`, no workspace moves, no
+(fdf9790, before any #150 change) fails at the *identical* assertion, and the
-failure dump. The comment says why: "a mini transition avoids a circular
+#150 refactor is proven inert here (the built `nomarchy-display-transition` /
-import on hyprland.nix". No PATH collision today (the mini is never installed;
+`nomarchy-keyboard-layout` have byte-identical store paths on HEAD vs the
-it is baked by store path into hypridle's wake tool via `display-tools.nix`),
+#150 branch). The `dock` transition itself succeeds (`result=ok`, both
-but nothing asserts the two stay behaviourally consistent, and this is the
+workspaces move, internal disabled) — only the post-reload re-dock invariant
-subsystem where #100/#142/#148 all lived. Pitch: extract the full tool into
+fails. Likely a harness/environment issue (the `enforce_dock_intent` tick
-its own module file (e.g. `modules/home/display-transition.nix`) imported by
+depends on the watcher reading `settings.display.dockMode` from the in-flake
-both hyprland.nix and idle.nix, delete the mini, re-run the
+state, which may not be writable in this NixOS-test sandbox) rather than a
-`tools/monitor-fallback.nix` harness + `checks.docking-ux` as the V2 gate.
+product regression — but it means the maintainer V2 dock harness is not a
-Cost: a focused refactor of safety-critical code — deliberately NOT done as
+usable gate until re-greened. Do first: reproduce, then check whether
-hygiene drive-by; deserves its own iteration.
+`set_dock_intent` actually persists `dockMode=true` inside the VM (grep the
+run journal for `dock-intent=…state-write-failed`); if the state write is the
+gap, the fix is in the harness, not the watcher.
 
 ### 149. `[watch]` Waybar's exec-once workaround may be defending against nothing post-linger
 

agent/HARDWARE-QUEUE.md

@@ -534,6 +534,21 @@ Everything else below stays open; order is convenience, not a gate.
       bar, notifications, and clipboard history (SUPER+V) work. This is
       the V3 close for the stale `graphical-session.target` /
       `start-limit-hit` relogin breakage (BACKLOG #149 note).
+- [ ] **#150 hypridle wake path now uses the FULL undock** — after pulling
+      the #150 commit + `nomarchy-home`: the hyprland-side transition/keyboard
+      tools are byte-identical (proven by store-path equality), so only the
+      hypridle wake behaviour changed. Two checks: **(a) suspend/resume while
+      docked** (lid closed, external on) — suspend, resume; pass = you land
+      back docked on the external with the panel still off and remembered
+      external-keyboard layouts intact (the wake now runs the full undock,
+      which `restore_keyboards` after any reload; the old mini did not). **(b)
+      zero-output rescue** — the #127 case (dock mode, external gone/black,
+      eDP disabled): pass = the internal panel comes back lit, workspaces move
+      to it, and `~/nomarchy-display-dump-*.txt` is written iff it stays dark.
+      Watch for a regression: the full undock clears dock-intent, so confirm a
+      *transient* zero-output blip on resume while genuinely still docked does
+      not leave you undocked with the laptop panel on (the external re-add
+      should re-dock via the watcher — verify it does).
 
 ## AMD dev box only
 - [ ] **#118 smartd still runs where drives DO have SMART** (this commit) — the

docs/ROADMAP.md

@@ -527,6 +527,25 @@ Design/decision records and a running log of shipped work (items marked
   V1: template HM activation built with `unstable.hello`, closure carries
   the unstable store path; `checks.unstable-seam` (eval-only) guards the
   seam permanently; lock diff added exactly the one node.
+- ✓ **Display-transition tool de-duplicated (#150, 2026-07-20):** the full
+  `nomarchy-display-transition` (dock/undock/enable — logging, the lid-inhibitor
+  gate, `restore_keyboards`, the failure dump) moved out of `hyprland.nix` into
+  its own leaf `modules/home/display-transition.nix`, and the keyboard helper it
+  calls into `modules/home/keyboard-tool.nix`; `hyprland.nix` and `idle.nix` now
+  import the ONE copy. This kills the lossy ~22-line mini `idle.nix` carried
+  under the same binary name to dodge a circular import — so the hypridle wake
+  path (`after_sleep` / DPMS `on-resume`) gets the real undock, i.e.
+  `restore_keyboards` after a reload and the evidence dump on enable-failure,
+  not a bare keyword+reload. Behaviour on the hyprland side is unchanged —
+  **proven** by byte-identical store paths for the built
+  `nomarchy-display-transition` / `nomarchy-keyboard-layout` on HEAD vs the
+  refactor. Gates: parse + home/toplevel builds + `checks.docking-ux`
+  (structural, `bash -n` + safety-feature greps) all green. The
+  `tools/monitor-fallback.nix` dock VM harness is **red on `main` already**
+  (the #148 reload-mid-dock assertion — identical failure on clean HEAD;
+  BACKLOG #154), so it could not gate this; the dock transition inside it
+  still ran `result=ok`. The idle wake-path behaviour change (full undock,
+  incl. dock-intent clearing + `restore_keyboards`) is V3 — HARDWARE-QUEUE.
 - ✓ **The idle brick's CAUSE found (#127 closed, 2026-07-17):** the incident
   was misdated — it did not happen "before 12:51:34 Jul 15" (that boot was
   healthy all day and ended in a routine clean reboot); it ended the

modules/home/display-transition.nix

@@ -0,0 +1,191 @@
+# The full dock / undock / enable display-transition primitive
+# (nomarchy-display-transition) — the one safety-critical copy. Extracted
+# from hyprland.nix (#150) so hyprland.nix and idle.nix share it instead of
+# idle.nix carrying a lossy mini that lacked logging, the lid-inhibitor
+# gate, restore_keyboards, and the failure dump.
+#
+# One transition primitive for the interactive Dock mode, abrupt undock,
+# and named profiles that disable the internal panel.  Dock is one Hyprland
+# batch: enable the target, move every internal workspace, focus it, then
+# disable the panel.  Undock deliberately enables the panel FIRST, waits
+# for it to become an active target, then restores every workspace.
+#
+#   sync            — nomarchy-state-sync exe (dock-intent writes)
+#   keyboardTool    — nomarchy-keyboard-layout (restore after reload)
+#   displayDumpTool — nomarchy-display-dump (evidence on enable failure)
+{ pkgs, sync, keyboardTool, displayDumpTool }:
+pkgs.writeShellScriptBin "nomarchy-display-transition" ''
+    set -u
+    LOGGER=${pkgs.util-linux}/bin/logger
+    log() { "$LOGGER" -t nomarchy-display-transition -- "$*"; }
+    valid_output() {
+      case "$1" in *[!A-Za-z0-9_.:-]*|"") return 1 ;; *) return 0 ;; esac
+    }
+    workspaces_on() {
+      hyprctl workspaces -j 2>/dev/null \
+        | jq -r --arg m "$1" '.[] | select(.monitor == $m and .id > 0) | .id'
+    }
+    all_workspaces() {
+      hyprctl workspaces -j 2>/dev/null | jq -r '.[] | select(.id > 0) | .id'
+    }
+    lid_inhibitor_held() {
+      ${pkgs.systemd}/bin/systemd-inhibit --list --json=short 2>/dev/null \
+        | ${pkgs.jq}/bin/jq -e 'any(.[]; .what == "handle-lid-switch" and .why == "Safe dock/undock display transition" and .mode == "block")' \
+            >/dev/null
+    }
+    batch_moves() { # stdin workspace ids, $1 target
+      target="$1"; commands=
+      while IFS= read -r ws; do
+        case "$ws" in *[!0-9]*|"") continue ;; esac
+        commands="$commands dispatch moveworkspacetomonitor $ws $target;"
+      done
+      printf '%s' "$commands"
+    }
+    # `monitors` (enabled-only) listing the output is the ONLY proof it is
+    # really on: every path here issues keywords hyprctl answers "ok" to
+    # without acting.  $1 = output, $2 = polls of 0.2s.
+    output_enabled() {
+      tries=0
+      while [ "$tries" -lt "$2" ]; do
+        hyprctl monitors -j 2>/dev/null \
+          | jq -e --arg m "$1" 'any(.[]; .name == $m)' >/dev/null && return 0
+        tries=$((tries+1)); sleep 0.2
+      done
+      return 1
+    }
+    # `hyprctl reload` re-reads the config, and every runtime keyword dies
+    # with it — including the `device[<name>]:kb_layout` the keyboard watcher
+    # applies to an external board.  Measured on hardware 2026-07-14: a bare
+    # reload took a keyboard remembered as `us` straight back to the session's
+    # `gb`, so without this the undock's escalation would silently break the
+    # layout of any keyboard that stays behind when the dock leaves (a
+    # wireless receiver in the laptop; only boards on the dock's own hub are
+    # unaffected, and only because they leave with it).  The remembered
+    # choices live in the in-flake state, so `restore` is authoritative.
+    restore_keyboards() {
+      hyprctl devices -j 2>/dev/null | jq -r '.keyboards[].name' 2>/dev/null \
+        | while IFS= read -r kb; do
+            [ -n "$kb" ] || continue
+            ${keyboardTool}/bin/nomarchy-keyboard-layout restore "$kb" \
+              >/dev/null 2>&1 || true
+          done
+    }
+
+    # Dock mode is an *intent*, and until #142 it lived only in the compositor:
+    # `keyword monitor <internal>, disable` and nothing written down. Any config
+    # reload re-applies the catch-all `monitor=,preferred,auto,1` and re-lights
+    # the panel — which is exactly why `undock` below uses `hyprctl reload` as
+    # its hammer — so every `nomarchy-home` silently performed an undock and the
+    # user re-picked Dock mode by hand.
+    #
+    # So record the intent where every other setting lives (the in-flake state,
+    # menu-writable), and let the watcher re-assert it. `--no-switch`: the
+    # watcher reads this at run time; a rebuild here would be both pointless and
+    # recursive. Failure to write is never fatal — a session that cannot reach
+    # the state file must still dock.
+    set_dock_intent() { # $1 = true|false
+      ${sync} --quiet set settings.display.dockMode "$1" --no-switch \
+        >/dev/null 2>&1 || log "dock-intent=$1 result=state-write-failed"
+    }
+
+    case "''${1:-}" in
+      dock)
+        internal="''${2:-}"; external="''${3:-}"
+        rule="''${4:-$external, preferred, auto, 1}"
+        valid_output "$internal" && valid_output "$external" \
+          || { echo "invalid monitor name" >&2; exit 64; }
+        # Fail closed: disabling the panel without this lock recreates the
+        # exact cable-removal → logind suspend race #100 is fixing.
+        lid_inhibitor_held \
+          || { log "transition=dock internal=$internal external=$external result=no-lid-inhibitor"; exit 1; }
+        moves=$(workspaces_on "$internal" | batch_moves "$external")
+        if hyprctl --batch \
+            "keyword monitor $rule; $moves dispatch focusmonitor $external; keyword monitor $internal, disable" \
+            >/dev/null 2>&1; then
+          set_dock_intent true
+          log "transition=dock internal=$internal external=$external result=ok"
+        else
+          log "transition=dock internal=$internal external=$external result=failed"
+          exit 1
+        fi ;;
+      undock)
+        internal="''${2:-}"
+        valid_output "$internal" || { echo "invalid monitor name" >&2; exit 64; }
+        # Clear the intent *first*: this path runs when the external is already
+        # gone, and if anything below fails the last thing the session needs is
+        # a watcher that keeps trying to dock to a monitor that left.
+        set_dock_intent false
+        # Safety-critical ordering: never remove/move away from an external
+        # before the internal panel is active and can receive workspaces.
+        #
+        # With ZERO enabled outputs — an abrupt undock, the panel already
+        # disabled by the dock — Hyprland 0.55.4 accepts `keyword monitor`
+        # (prints "ok", exits 0) and then never flushes it: the rule is held
+        # until some DRM event arrives, and the panel stays dark.  This is
+        # deterministic, not a race.  Probed on hardware 2026-07-14: the
+        # keyword was inert across 4s and 5s windows in two separate runs,
+        # `dispatch forcerendererreload` did not flush it either, and only
+        # `hyprctl reload` did — in 99ms and 289ms, with the cable out.
+        #
+        # Round 6 read the same symptom as a teardown race and re-issued the
+        # keyword 25 times a poll.  Retrying an inert command cannot work: it
+        # bought 30s of black screen and every `result=ok` in that journal was
+        # really the user plugging the cable back in, whose hotplug flushed
+        # the queued rule and let the next poll take the credit.
+        #
+        # So issue the keyword once — enough whenever another output is still
+        # enabled, e.g. the menu's Dock mode toggle — and escalate to the
+        # reload hammer only when it proves inert.
+        hyprctl keyword monitor "$internal,preferred,auto,1" >/dev/null 2>&1
+        if ! output_enabled "$internal" 5; then
+          log "transition=undock internal=$internal keyword=inert escalate=reload"
+          hyprctl reload >/dev/null 2>&1
+          if ! output_enabled "$internal" 25; then
+            log "transition=undock internal=$internal result=enable-failed"
+            # #127: leave evidence on disk without SSH (TTY or next login).
+            ${displayDumpTool}/bin/nomarchy-display-dump undock-enable-failed \
+              >/dev/null 2>&1 || true
+            exit 1
+          fi
+          # The config's monitor rules own the panel now.  Re-assert the
+          # runtime rule — which flushes normally, an output being enabled
+          # again — so a config that parks the panel off cannot undo the
+          # undock, and give the keyboards back what the reload took.
+          hyprctl keyword monitor "$internal,preferred,auto,1" >/dev/null 2>&1
+          restore_keyboards
+          log "transition=undock internal=$internal enable=via-reload"
+        fi
+        moves=$(all_workspaces | batch_moves "$internal")
+        hyprctl --batch "$moves dispatch focusmonitor $internal" >/dev/null 2>&1 \
+          || { log "transition=undock internal=$internal result=move-failed"; exit 1; }
+        # #127: undock after idle DPMS left the seat black even when the
+        # panel was re-enabled — always light the chain after enable.
+        hyprctl dispatch dpms on >/dev/null 2>&1 || true
+        log "transition=undock internal=$internal result=ok" ;;
+      enable)
+        internal="''${2:-}"
+        valid_output "$internal" || exit 64
+        # Menu ▸ Display ▸ "Screen on". Turning the laptop panel back on *is*
+        # leaving dock mode, and saying so is what stops the watcher from
+        # re-docking the panel out from under the user a second later (#142).
+        # Only the internal clears the intent: lighting some third monitor is
+        # not a statement about the lid.
+        case "$internal" in
+          eDP*|LVDS*|DSI*) set_dock_intent false ;;
+        esac
+        # Reachable only from the menu, i.e. with a screen already on, so the
+        # keyword flushes and no reload escalation is needed — but still make
+        # `monitors` the proof, or the menu's "back on" notification cheers
+        # for a keyword hyprctl merely said "ok" to.
+        hyprctl keyword monitor "$internal,preferred,auto,1" >/dev/null 2>&1
+        if output_enabled "$internal" 10; then
+          hyprctl dispatch dpms on >/dev/null 2>&1 || true
+          true
+        else
+          false
+        fi ;;
+      *)
+        echo "usage: nomarchy-display-transition [dock <internal> <external> [external-rule]|undock <internal>|enable <internal>]" >&2
+        exit 64 ;;
+    esac
+  ''

modules/home/hyprland.nix

@@ -128,186 +128,11 @@ let
   displayDumpTool =
     (import ./display-tools.nix { inherit pkgs; }).displayDumpTool;
 
-  # One transition primitive for the interactive Dock mode, abrupt undock,
+  # The full dock/undock/enable transition primitive lives in its own file
-  # and named profiles that disable the internal panel.  Dock is one Hyprland
+  # so idle.nix shares this exact safety-critical copy (#150), not a mini.
-  # batch: enable the target, move every internal workspace, focus it, then
+  displayTransitionTool = import ./display-transition.nix {
-  # disable the panel.  Undock deliberately enables the panel FIRST, waits
+    inherit pkgs sync keyboardTool displayDumpTool;
-  # for it to become an active target, then restores every workspace.
+  };
-  displayTransitionTool = pkgs.writeShellScriptBin "nomarchy-display-transition" ''
-    set -u
-    LOGGER=${pkgs.util-linux}/bin/logger
-    log() { "$LOGGER" -t nomarchy-display-transition -- "$*"; }
-    valid_output() {
-      case "$1" in *[!A-Za-z0-9_.:-]*|"") return 1 ;; *) return 0 ;; esac
-    }
-    workspaces_on() {
-      hyprctl workspaces -j 2>/dev/null \
-        | jq -r --arg m "$1" '.[] | select(.monitor == $m and .id > 0) | .id'
-    }
-    all_workspaces() {
-      hyprctl workspaces -j 2>/dev/null | jq -r '.[] | select(.id > 0) | .id'
-    }
-    lid_inhibitor_held() {
-      ${pkgs.systemd}/bin/systemd-inhibit --list --json=short 2>/dev/null \
-        | ${pkgs.jq}/bin/jq -e 'any(.[]; .what == "handle-lid-switch" and .why == "Safe dock/undock display transition" and .mode == "block")' \
-            >/dev/null
-    }
-    batch_moves() { # stdin workspace ids, $1 target
-      target="$1"; commands=
-      while IFS= read -r ws; do
-        case "$ws" in *[!0-9]*|"") continue ;; esac
-        commands="$commands dispatch moveworkspacetomonitor $ws $target;"
-      done
-      printf '%s' "$commands"
-    }
-    # `monitors` (enabled-only) listing the output is the ONLY proof it is
-    # really on: every path here issues keywords hyprctl answers "ok" to
-    # without acting.  $1 = output, $2 = polls of 0.2s.
-    output_enabled() {
-      tries=0
-      while [ "$tries" -lt "$2" ]; do
-        hyprctl monitors -j 2>/dev/null \
-          | jq -e --arg m "$1" 'any(.[]; .name == $m)' >/dev/null && return 0
-        tries=$((tries+1)); sleep 0.2
-      done
-      return 1
-    }
-    # `hyprctl reload` re-reads the config, and every runtime keyword dies
-    # with it — including the `device[<name>]:kb_layout` the keyboard watcher
-    # applies to an external board.  Measured on hardware 2026-07-14: a bare
-    # reload took a keyboard remembered as `us` straight back to the session's
-    # `gb`, so without this the undock's escalation would silently break the
-    # layout of any keyboard that stays behind when the dock leaves (a
-    # wireless receiver in the laptop; only boards on the dock's own hub are
-    # unaffected, and only because they leave with it).  The remembered
-    # choices live in the in-flake state, so `restore` is authoritative.
-    restore_keyboards() {
-      hyprctl devices -j 2>/dev/null | jq -r '.keyboards[].name' 2>/dev/null \
-        | while IFS= read -r kb; do
-            [ -n "$kb" ] || continue
-            ${keyboardTool}/bin/nomarchy-keyboard-layout restore "$kb" \
-              >/dev/null 2>&1 || true
-          done
-    }
-
-    # Dock mode is an *intent*, and until #142 it lived only in the compositor:
-    # `keyword monitor <internal>, disable` and nothing written down. Any config
-    # reload re-applies the catch-all `monitor=,preferred,auto,1` and re-lights
-    # the panel — which is exactly why `undock` below uses `hyprctl reload` as
-    # its hammer — so every `nomarchy-home` silently performed an undock and the
-    # user re-picked Dock mode by hand.
-    #
-    # So record the intent where every other setting lives (the in-flake state,
-    # menu-writable), and let the watcher re-assert it. `--no-switch`: the
-    # watcher reads this at run time; a rebuild here would be both pointless and
-    # recursive. Failure to write is never fatal — a session that cannot reach
-    # the state file must still dock.
-    set_dock_intent() { # $1 = true|false
-      ${sync} --quiet set settings.display.dockMode "$1" --no-switch \
-        >/dev/null 2>&1 || log "dock-intent=$1 result=state-write-failed"
-    }
-
-    case "''${1:-}" in
-      dock)
-        internal="''${2:-}"; external="''${3:-}"
-        rule="''${4:-$external, preferred, auto, 1}"
-        valid_output "$internal" && valid_output "$external" \
-          || { echo "invalid monitor name" >&2; exit 64; }
-        # Fail closed: disabling the panel without this lock recreates the
-        # exact cable-removal → logind suspend race #100 is fixing.
-        lid_inhibitor_held \
-          || { log "transition=dock internal=$internal external=$external result=no-lid-inhibitor"; exit 1; }
-        moves=$(workspaces_on "$internal" | batch_moves "$external")
-        if hyprctl --batch \
-            "keyword monitor $rule; $moves dispatch focusmonitor $external; keyword monitor $internal, disable" \
-            >/dev/null 2>&1; then
-          set_dock_intent true
-          log "transition=dock internal=$internal external=$external result=ok"
-        else
-          log "transition=dock internal=$internal external=$external result=failed"
-          exit 1
-        fi ;;
-      undock)
-        internal="''${2:-}"
-        valid_output "$internal" || { echo "invalid monitor name" >&2; exit 64; }
-        # Clear the intent *first*: this path runs when the external is already
-        # gone, and if anything below fails the last thing the session needs is
-        # a watcher that keeps trying to dock to a monitor that left.
-        set_dock_intent false
-        # Safety-critical ordering: never remove/move away from an external
-        # before the internal panel is active and can receive workspaces.
-        #
-        # With ZERO enabled outputs — an abrupt undock, the panel already
-        # disabled by the dock — Hyprland 0.55.4 accepts `keyword monitor`
-        # (prints "ok", exits 0) and then never flushes it: the rule is held
-        # until some DRM event arrives, and the panel stays dark.  This is
-        # deterministic, not a race.  Probed on hardware 2026-07-14: the
-        # keyword was inert across 4s and 5s windows in two separate runs,
-        # `dispatch forcerendererreload` did not flush it either, and only
-        # `hyprctl reload` did — in 99ms and 289ms, with the cable out.
-        #
-        # Round 6 read the same symptom as a teardown race and re-issued the
-        # keyword 25 times a poll.  Retrying an inert command cannot work: it
-        # bought 30s of black screen and every `result=ok` in that journal was
-        # really the user plugging the cable back in, whose hotplug flushed
-        # the queued rule and let the next poll take the credit.
-        #
-        # So issue the keyword once — enough whenever another output is still
-        # enabled, e.g. the menu's Dock mode toggle — and escalate to the
-        # reload hammer only when it proves inert.
-        hyprctl keyword monitor "$internal,preferred,auto,1" >/dev/null 2>&1
-        if ! output_enabled "$internal" 5; then
-          log "transition=undock internal=$internal keyword=inert escalate=reload"
-          hyprctl reload >/dev/null 2>&1
-          if ! output_enabled "$internal" 25; then
-            log "transition=undock internal=$internal result=enable-failed"
-            # #127: leave evidence on disk without SSH (TTY or next login).
-            ${displayDumpTool}/bin/nomarchy-display-dump undock-enable-failed \
-              >/dev/null 2>&1 || true
-            exit 1
-          fi
-          # The config's monitor rules own the panel now.  Re-assert the
-          # runtime rule — which flushes normally, an output being enabled
-          # again — so a config that parks the panel off cannot undo the
-          # undock, and give the keyboards back what the reload took.
-          hyprctl keyword monitor "$internal,preferred,auto,1" >/dev/null 2>&1
-          restore_keyboards
-          log "transition=undock internal=$internal enable=via-reload"
-        fi
-        moves=$(all_workspaces | batch_moves "$internal")
-        hyprctl --batch "$moves dispatch focusmonitor $internal" >/dev/null 2>&1 \
-          || { log "transition=undock internal=$internal result=move-failed"; exit 1; }
-        # #127: undock after idle DPMS left the seat black even when the
-        # panel was re-enabled — always light the chain after enable.
-        hyprctl dispatch dpms on >/dev/null 2>&1 || true
-        log "transition=undock internal=$internal result=ok" ;;
-      enable)
-        internal="''${2:-}"
-        valid_output "$internal" || exit 64
-        # Menu ▸ Display ▸ "Screen on". Turning the laptop panel back on *is*
-        # leaving dock mode, and saying so is what stops the watcher from
-        # re-docking the panel out from under the user a second later (#142).
-        # Only the internal clears the intent: lighting some third monitor is
-        # not a statement about the lid.
-        case "$internal" in
-          eDP*|LVDS*|DSI*) set_dock_intent false ;;
-        esac
-        # Reachable only from the menu, i.e. with a screen already on, so the
-        # keyword flushes and no reload escalation is needed — but still make
-        # `monitors` the proof, or the menu's "back on" notification cheers
-        # for a keyword hyprctl merely said "ok" to.
-        hyprctl keyword monitor "$internal,preferred,auto,1" >/dev/null 2>&1
-        if output_enabled "$internal" 10; then
-          hyprctl dispatch dpms on >/dev/null 2>&1 || true
-          true
-        else
-          false
-        fi ;;
-      *)
-        echo "usage: nomarchy-display-transition [dock <internal> <external> [external-rule]|undock <internal>|enable <internal>]" >&2
-        exit 64 ;;
-    esac
-  '';
 
   displayWakeTool =
     (import ./display-tools.nix {
@@ -786,78 +611,7 @@ ${lib.concatStringsSep "\n" (lib.mapAttrsToList
     done
   '';
 
-  # Candidate layouts offered by the new-keyboard picker: the session
+  keyboardTool = import ./keyboard-tool.nix { inherit pkgs lib config; };
-  # layout(s) (nomarchy.keyboard.layout, comma-split for a multi-layout
-  # session) plus the extra nomarchy.keyboard.layouts pool. The pool is
-  # deliberately NOT merged into input.kb_layout — those candidates are for
-  # *external* keyboards and get applied per-device by the watcher's apply().
-  # Loading them onto the session keyboard is what let a global switch flip
-  # the built-in board to the wrong layout.
-  pickerLayouts = lib.unique (
-    (lib.splitString "," config.nomarchy.keyboard.layout)
-    ++ config.nomarchy.keyboard.layouts
-  );
-
-  # Per-device keyboard helper shared by the hotplug watcher and the manual
-  # System › Keyboard menu.  The configured candidates are listed first, then
-  # every XKB layout known to the system, so the feature works on a default
-  # install instead of silently disappearing until home.nix is edited.
-  keyboardTool = pkgs.writeShellScriptBin "nomarchy-keyboard-layout" ''
-    set -u
-    sync=${sync}
-
-    layouts() {
-      printf '%s\n' ${lib.concatMapStringsSep " " lib.escapeShellArg pickerLayouts}
-      ${pkgs.gawk}/bin/awk '
-        /^! layout/ { in_layouts=1; next }
-        /^!/ && in_layouts { exit }
-        in_layouts && NF { print $1 }
-      ' ${pkgs.xkeyboard_config}/share/X11/xkb/rules/base.lst
-    }
-    saved_map() { "$sync" get settings.keyboard.devices 2>/dev/null || echo '{}'; }
-    saved_for() { saved_map | jq -r --arg k "$1" '.[$k] // empty'; }
-    apply_runtime() { hyprctl keyword "device[$1]:kb_layout" "$2" >/dev/null 2>&1; }
-
-    case "''${1:-}" in
-      layouts)
-        layouts | ${pkgs.gawk}/bin/awk 'NF && !seen[$0]++' ;;
-      devices)
-        hyprctl devices -j 2>/dev/null \
-          | jq -r '.keyboards[] | "\(.name)\t\(.active_keymap // \"unknown\")"' ;;
-      saved)
-        [ -n "''${2:-}" ] || exit 64
-        saved_for "$2" ;;
-      restore)
-        [ -n "''${2:-}" ] || exit 64
-        layout=$(saved_for "$2")
-        [ -n "$layout" ] && apply_runtime "$2" "$layout" ;;
-      apply)
-        [ -n "''${2:-}" ] && [ -n "''${3:-}" ] || exit 64
-        layouts | ${pkgs.gnugrep}/bin/grep -Fxq "$3" \
-          || { notify-send "Keyboard" "Unknown XKB layout: $3"; exit 64; }
-        if apply_runtime "$2" "$3"; then
-          map=$(saved_map | jq -c --arg k "$2" --arg v "$3" '. + {($k): $v}') || exit 1
-          if "$sync" --quiet set settings.keyboard.devices "$map" --no-switch; then
-            notify-send "Keyboard" "$2 → $3"
-          else
-            notify-send "Keyboard" "$2 → $3 for this session, but the choice could not be saved."
-            exit 1
-          fi
-        else
-          notify-send "Keyboard" "Could not apply $3 to $2."
-          exit 1
-        fi ;;
-      forget)
-        [ -n "''${2:-}" ] || exit 64
-        map=$(saved_map | jq -c --arg k "$2" 'del(.[$k])') || exit 1
-        "$sync" --quiet set settings.keyboard.devices "$map" --no-switch || exit 1
-        apply_runtime "$2" ${lib.escapeShellArg config.nomarchy.keyboard.layout} || true
-        notify-send "Keyboard" "$2 now follows the session layout." ;;
-      *)
-        echo "usage: nomarchy-keyboard-layout [layouts|devices|saved <device>|restore <device>|apply <device> <layout>|forget <device>]" >&2
-        exit 64 ;;
-    esac
-  '';
 
   # On a keyboard that connects after login (not declared in
   # keyboard.devices, not already remembered), ask for a layout and persist it

modules/home/idle.nix

@@ -21,35 +21,23 @@ let
   '';
 
   # Absolute store paths for hypridle (thin PATH). Wake reuses the shared
-  # helper; a mini transition avoids a circular import on hyprland.nix.
+  # helper AND the full display-transition tool (#150): idle.nix used to
+  # carry a lossy mini copy to dodge a circular import on hyprland.nix, but
+  # both live in leaf files now, so the wake path gets the real undock —
+  # logging, the enable-failure dump, and restore_keyboards after a reload.
   displayWake =
     let
-      miniTransition = pkgs.writeShellScriptBin "nomarchy-display-transition" ''
+      keyboardTool = import ./keyboard-tool.nix { inherit pkgs lib config; };
-        set -u
+      displayDumpTool =
-        case "''${1:-}" in
+        (import ./display-tools.nix { inherit pkgs; }).displayDumpTool;
-          undock|enable)
+      displayTransition = import ./display-transition.nix {
-            internal="''${2:-}"
+        inherit pkgs keyboardTool displayDumpTool;
-            [ -n "$internal" ] || exit 64
+        sync = lib.getExe config.nomarchy.package;
-            hyprctl keyword monitor "$internal,preferred,auto,1" >/dev/null 2>&1 || true
+      };
-            if ! hyprctl monitors -j 2>/dev/null \
-                  | ${pkgs.jq}/bin/jq -e --arg m "$internal" 'any(.[]; .name == $m)' \
-                  >/dev/null 2>&1; then
-              hyprctl reload >/dev/null 2>&1 || true
-              sleep 0.5
-            fi
-            hyprctl keyword monitor "$internal,preferred,auto,1" >/dev/null 2>&1 || true
-            hyprctl dispatch dpms on >/dev/null 2>&1 || true
-            hyprctl monitors -j 2>/dev/null \
-              | ${pkgs.jq}/bin/jq -e --arg m "$internal" 'any(.[]; .name == $m)' \
-              >/dev/null 2>&1
-            ;;
-          *) exit 64 ;;
-        esac
-      '';
     in
     (import ./display-tools.nix {
       inherit pkgs;
-      displayTransition = miniTransition;
+      inherit displayTransition;
     }).displayWakeTool;
 in
 {

modules/home/keyboard-tool.nix

@@ -0,0 +1,81 @@
+# The per-device keyboard-layout helper (nomarchy-keyboard-layout).
+# Extracted from hyprland.nix (#150) so it is built ONCE and shared: the
+# Hyprland module puts it on PATH and drives it from the hotplug watcher,
+# while the display-transition tool calls it (restore_keyboards) after a
+# config reload. Pass the module's { pkgs, lib, config }.
+{ pkgs, lib, config }:
+let
+  sync = lib.getExe config.nomarchy.package;
+
+  # Candidate layouts offered by the new-keyboard picker: the session
+  # layout(s) (nomarchy.keyboard.layout, comma-split for a multi-layout
+  # session) plus the extra nomarchy.keyboard.layouts pool. The pool is
+  # deliberately NOT merged into input.kb_layout — those candidates are for
+  # *external* keyboards and get applied per-device by the watcher's apply().
+  # Loading them onto the session keyboard is what let a global switch flip
+  # the built-in board to the wrong layout.
+  pickerLayouts = lib.unique (
+    (lib.splitString "," config.nomarchy.keyboard.layout)
+    ++ config.nomarchy.keyboard.layouts
+  );
+in
+# Per-device keyboard helper shared by the hotplug watcher and the manual
+# System › Keyboard menu.  The configured candidates are listed first, then
+# every XKB layout known to the system, so the feature works on a default
+# install instead of silently disappearing until home.nix is edited.
+pkgs.writeShellScriptBin "nomarchy-keyboard-layout" ''
+    set -u
+    sync=${sync}
+
+    layouts() {
+      printf '%s\n' ${lib.concatMapStringsSep " " lib.escapeShellArg pickerLayouts}
+      ${pkgs.gawk}/bin/awk '
+        /^! layout/ { in_layouts=1; next }
+        /^!/ && in_layouts { exit }
+        in_layouts && NF { print $1 }
+      ' ${pkgs.xkeyboard_config}/share/X11/xkb/rules/base.lst
+    }
+    saved_map() { "$sync" get settings.keyboard.devices 2>/dev/null || echo '{}'; }
+    saved_for() { saved_map | jq -r --arg k "$1" '.[$k] // empty'; }
+    apply_runtime() { hyprctl keyword "device[$1]:kb_layout" "$2" >/dev/null 2>&1; }
+
+    case "''${1:-}" in
+      layouts)
+        layouts | ${pkgs.gawk}/bin/awk 'NF && !seen[$0]++' ;;
+      devices)
+        hyprctl devices -j 2>/dev/null \
+          | jq -r '.keyboards[] | "\(.name)\t\(.active_keymap // \"unknown\")"' ;;
+      saved)
+        [ -n "''${2:-}" ] || exit 64
+        saved_for "$2" ;;
+      restore)
+        [ -n "''${2:-}" ] || exit 64
+        layout=$(saved_for "$2")
+        [ -n "$layout" ] && apply_runtime "$2" "$layout" ;;
+      apply)
+        [ -n "''${2:-}" ] && [ -n "''${3:-}" ] || exit 64
+        layouts | ${pkgs.gnugrep}/bin/grep -Fxq "$3" \
+          || { notify-send "Keyboard" "Unknown XKB layout: $3"; exit 64; }
+        if apply_runtime "$2" "$3"; then
+          map=$(saved_map | jq -c --arg k "$2" --arg v "$3" '. + {($k): $v}') || exit 1
+          if "$sync" --quiet set settings.keyboard.devices "$map" --no-switch; then
+            notify-send "Keyboard" "$2 → $3"
+          else
+            notify-send "Keyboard" "$2 → $3 for this session, but the choice could not be saved."
+            exit 1
+          fi
+        else
+          notify-send "Keyboard" "Could not apply $3 to $2."
+          exit 1
+        fi ;;
+      forget)
+        [ -n "''${2:-}" ] || exit 64
+        map=$(saved_map | jq -c --arg k "$2" 'del(.[$k])') || exit 1
+        "$sync" --quiet set settings.keyboard.devices "$map" --no-switch || exit 1
+        apply_runtime "$2" ${lib.escapeShellArg config.nomarchy.keyboard.layout} || true
+        notify-send "Keyboard" "$2 now follows the session layout." ;;
+      *)
+        echo "usage: nomarchy-keyboard-layout [layouts|devices|saved <device>|restore <device>|apply <device> <layout>|forget <device>]" >&2
+        exit 64 ;;
+    esac
+  ''