Fix live network and phone discovery

# Conflicts:
#	config/dot/quickshell/modules/settings/HealthPage.qml
#	tests/quickshell/health-ui-contract.sh

.gitignore

@@ -20,3 +20,4 @@ __pycache__/
 # Generated from the colour scheme; machine state, not configuration.
 /config/dot/gtk-3.0/settings.ini
 /config/dot/gtk-4.0/settings.ini
+/config/dot/tmux/current-theme.conf

config/dot/btop/themes/tokyonight-day.theme

@@ -0,0 +1,57 @@
+# Tokyo Night Day for btop, the light counterpart to tokyonight-moon.
+#
+# btop ships no Tokyo Night light variant at all, and the nearest stock light
+# theme (flat-remix-light) is a different palette that happens to have a similar
+# background. Same colours as kitty/themes/tokyonight-day.conf so the terminal
+# and what runs inside it cannot disagree.
+#
+# Gradients keep the same low -> middle -> high meaning as the dark theme, using
+# Day's darker, more saturated accents: the light versions of these hues are too
+# faint to read as a filled meter.
+
+theme[main_bg]="#e1e2e7"
+theme[main_fg]="#3760bf"
+theme[title]="#3760bf"
+theme[hi_fg]="#2e7de9"
+theme[selected_bg]="#c4c8da"
+theme[selected_fg]="#2e7de9"
+theme[inactive_fg]="#7079a8"
+theme[proc_misc]="#587539"
+
+theme[cpu_box]="#a8aecb"
+theme[mem_box]="#a8aecb"
+theme[net_box]="#a8aecb"
+theme[proc_box]="#a8aecb"
+theme[div_line]="#c4c8da"
+
+theme[temp_start]="#2e7de9"
+theme[temp_mid]="#8c6c3e"
+theme[temp_end]="#f52a65"
+
+theme[cpu_start]="#2e7de9"
+theme[cpu_mid]="#9854f1"
+theme[cpu_end]="#f52a65"
+
+theme[free_start]="#c4c8da"
+theme[free_mid]="#007197"
+theme[free_end]="#2e7de9"
+
+theme[cached_start]="#007197"
+theme[cached_mid]="#2e7de9"
+theme[cached_end]="#9854f1"
+
+theme[available_start]="#8c6c3e"
+theme[available_mid]="#b15c00"
+theme[available_end]="#f52a65"
+
+theme[used_start]="#587539"
+theme[used_mid]="#8c6c3e"
+theme[used_end]="#f52a65"
+
+theme[download_start]="#c4c8da"
+theme[download_mid]="#2e7de9"
+theme[download_end]="#007197"
+
+theme[upload_start]="#c4c8da"
+theme[upload_mid]="#9854f1"
+theme[upload_end]="#7847bd"

config/dot/btop/themes/tokyonight-moon.theme

@@ -0,0 +1,56 @@
+# Tokyo Night Moon for btop, matched to Panama's palette.
+#
+# btop ships a "tokyo-night" theme, but it is the Night variant (#1a1b26). The
+# rest of this desktop is Moon (#222436), and two Tokyo Nights side by side read
+# as a mistake rather than as a choice.
+#
+# The *_start/_mid/_end triples are gradients btop draws meters with: low,
+# middle, and high. They run blue -> yellow -> red so a saturated resource is
+# obvious at a glance without reading the number.
+
+theme[main_bg]="#222436"
+theme[main_fg]="#c8d3f5"
+theme[title]="#c8d3f5"
+theme[hi_fg]="#82aaff"
+theme[selected_bg]="#3b4261"
+theme[selected_fg]="#82aaff"
+theme[inactive_fg]="#636da6"
+theme[proc_misc]="#a5e8b5"
+
+theme[cpu_box]="#4d5685"
+theme[mem_box]="#4d5685"
+theme[net_box]="#4d5685"
+theme[proc_box]="#4d5685"
+theme[div_line]="#3b4261"
+
+theme[temp_start]="#82aaff"
+theme[temp_mid]="#ffc777"
+theme[temp_end]="#ff757f"
+
+theme[cpu_start]="#82aaff"
+theme[cpu_mid]="#c099ff"
+theme[cpu_end]="#ff757f"
+
+theme[free_start]="#3b4261"
+theme[free_mid]="#589ed7"
+theme[free_end]="#86e1fc"
+
+theme[cached_start]="#86e1fc"
+theme[cached_mid]="#82aaff"
+theme[cached_end]="#c099ff"
+
+theme[available_start]="#ffc777"
+theme[available_mid]="#ff966c"
+theme[available_end]="#ff757f"
+
+theme[used_start]="#a5e8b5"
+theme[used_mid]="#ffc777"
+theme[used_end]="#ff757f"
+
+theme[download_start]="#3b4261"
+theme[download_mid]="#82aaff"
+theme[download_end]="#86e1fc"
+
+theme[upload_start]="#3b4261"
+theme[upload_mid]="#c099ff"
+theme[upload_end]="#fca7ea"

config/dot/hypr/DESKTOP-PARITY.md

@@ -37,6 +37,31 @@ Last live audit: 2026-08-17, Fedora 44, Hyprland 0.56.2, Quickshell 0.3.0.
 | Autostart apps | Nextcloud, Bitwarden, and RustDesk system service/tray | Live |
 | Printer administration | CUPS with the `system-config-printer` graphical interface | Live |
 | System settings | The Settings app for display policy, appearance, desktop, sound, focus, shortcuts, and services; labelled GNOME hardware/account handoffs | Live |
+| System health and recovery | Settings → System Health, `Panama: Check System Health` in Vicinae, a degraded-only bar indicator, redacted reports, and bounded Panama-owned repairs | Live |
+
+## System health and recovery
+
+Panama stays silent while the desktop is healthy. A compact bar indicator
+appears only for actionable warnings or errors and opens the same **System
+Health** page available from Settings and the Vicinae command **Panama: Check
+System Health**. The terminal summary is available with:
+
+```bash
+~/.config/quickshell/scripts/panama-doctor --summary
+```
+
+The doctor reports authored, redacted observations about Panama-owned services,
+tools, links, and configured integrations. It does not read secrets, clipboard
+or notification contents, calendar events, SSIDs, or device addresses. Repairs
+are a small allow-list: Panama user services, Panama-owned links and launcher
+commands, duplicate Panama Caffeine inhibitors, and a confirmed shell restart.
+They never install packages, invoke `sudo`, delete user data, or rewrite
+arbitrary configuration.
+
+Generic Fedora configuration remains with the system tools that own it. The
+final System Health card hands network settings, users, sharing, colour
+profiles, and digital wellbeing to their exact GNOME Settings panels rather
+than presenting inert Hyprland controls.
 
 ## GNOME extension migration
 

config/dot/hypr/input.lua

@@ -21,10 +21,18 @@ hl.config({
         repeat_delay = prefs.get("keyRepeatDelay", 500),
         repeat_rate  = prefs.get("keyRepeatRate", 33),
 
-        -- 1 = click to focus. GNOME's behaviour; NOT sloppy focus.
+        -- 1 = FOLLOW. The window under the pointer takes focus. This comment
+        -- previously claimed 1 was "click to focus, GNOME's behaviour", which
+        -- is the opposite of what Hyprland does -- `hyprctl descriptions` gives
+        -- map: [{"separate":3},{"detached":2},{"follow":1},{"disabled":0}],
+        -- so click-to-focus is 0. Changing the shipped value is a behaviour
+        -- decision rather than a correction, so the value is left alone and
+        -- only the description is fixed; Settings exposes all four.
         follow_mouse = prefs.getInt("followMouse", 1),
 
-        -- Don't refocus on mouse move alone -- only on click.
+        -- Softens follow_mouse: with this off, focus changes only when the
+        -- pointer crosses a window boundary, not on every movement inside one.
+        -- Still focus-follows-pointer, just less twitchy.
         mouse_refocus = false,
 
         -- Flat pointer response, no acceleration. Matters for gaming.

config/dot/quickshell/config/DesktopPreferences.qml

@@ -98,7 +98,26 @@ Singleton {
             // back to shipped defaults and let the next write replace it.
             parsed = {};
         }
-        root.values = (parsed && typeof parsed === "object") ? parsed : {};
+        const raw = (parsed && typeof parsed === "object") ? parsed : {};
+
+        // Upgrade before anything reads a value. A stored key the current
+        // schema no longer recognises is carried through untouched and silently
+        // stops taking effect, so the conversion has to happen here rather than
+        // being noticed later by whoever owns that setting.
+        const result = Migrations.apply(raw);
+        root.values = result.values;
+
+        if (result.migrated)
+            console.info("Settings migrated from version", result.from, "to", result.to + ":",
+                         result.applied.join("; "));
+
+        // Write whenever the version moved, which includes stamping a file
+        // written before versioning existed. Left unwritten, the stamp lives
+        // only in memory and is redone on every launch, and a migration that is
+        // not idempotent would compound.
+        if (result.changed)
+            persistTimer.restart();
+
         root.revision++;
         root.loaded = true;
     }

config/dot/quickshell/config/Migrations.qml

@@ -0,0 +1,121 @@
+pragma Singleton
+
+// Versioned upgrades for the settings file.
+//
+// The schema is the single source of truth for what a setting IS, but it cannot
+// describe what a setting USED to be. Renaming a key, changing its units, or
+// splitting one setting into two all leave a stored value that the new schema
+// does not recognise -- and an unrecognised key is silently carried through
+// untouched, so the user's choice simply stops taking effect with nothing to
+// say why. That is the failure this exists to prevent.
+//
+// HOW IT WORKS
+//
+// settings.json carries a schemaVersion. On load, every migration with a
+// version ABOVE the stored one runs in order, then the file is stamped with
+// `current`. A file with no schemaVersion at all is a file written before this
+// existed; it is stamped at `baseline` and NOT migrated, because those
+// migrations were never written for it.
+//
+// WRITING ONE
+//
+//   { version: 2, describe: "rename dockDelay to dockHideDelayMs",
+//     migrate: values => { ... return values; } }
+//
+// Rules that make this safe to run against a real user's file:
+//
+//   * migrate() receives the whole values object and returns it. Mutating and
+//     returning the same object is fine.
+//   * NEVER delete a key you are not replacing. Unknown keys are deliberately
+//     preserved so that rolling back to an older Panama does not discard a
+//     newer version's settings, and a migration is the one place that promise
+//     could quietly be broken.
+//   * A migration must tolerate its input being absent or the wrong type. It
+//     runs against files written by every previous version, including ones
+//     that were hand-edited.
+//   * Migrations never run twice: the stored version only moves forward.
+
+import QtQuick
+
+QtObject {
+    id: root
+
+    // What a file written today is stamped with. Bump this when adding a
+    // migration, to the version of the migration you added.
+    readonly property int current: 1
+
+    // Files predating versioning are stamped here without being migrated.
+    readonly property int baseline: 1
+
+    readonly property string versionKey: "schemaVersion"
+
+    // Ordered by version. Empty is the correct state until the first breaking
+    // schema change -- this exists so that change is a routine edit rather than
+    // an emergency.
+    readonly property var steps: []
+
+    function storedVersion(values: var): int {
+        const raw = values ? values[root.versionKey] : undefined;
+        return (typeof raw === "number" && isFinite(raw)) ? Math.floor(raw) : 0;
+    }
+
+    // Returns { values, migrated, changed, from, to, applied }.
+    //
+    // `applied` names each step that ran, so the caller can log something
+    // meaningful rather than "settings changed somehow". `changed` is the one
+    // the caller should write on: stamping a pre-versioning file changes it
+    // without running any step, and left unwritten the stamp would live only in
+    // memory and be redone on every launch.
+    function apply(values: var): var {
+        return root.applyWith(values, root.steps, root.current, root.baseline);
+    }
+
+    // The same logic with the step list injected, so the machinery can be
+    // tested against fixture migrations. The real list is empty until the first
+    // breaking schema change, and a mechanism that has never run against a
+    // failing step is not one to find out about during an upgrade.
+    function applyWith(values: var, steps: var, current: int, baseline: int): var {
+        const safe = (values && typeof values === "object") ? values : {};
+        const from = root.storedVersion(safe);
+
+        // No version: written before versioning existed. Stamp it and stop.
+        // Running the migration list against it would apply upgrades designed
+        // for schemas this file never had.
+        if (from === 0) {
+            safe[root.versionKey] = baseline;
+            return { values: safe, migrated: false, changed: true, from: 0, to: baseline, applied: [] };
+        }
+
+        // A file from a NEWER Panama. Left completely alone: downgrading its
+        // keys is not something this can do correctly, and unknown keys are
+        // already preserved, so the older build simply ignores what it does not
+        // understand.
+        if (from > current)
+            return { values: safe, migrated: false, changed: false, from: from, to: from, applied: [] };
+
+        const applied = [];
+        let working = safe;
+        for (const step of steps) {
+            if (step.version <= from || step.version > current)
+                continue;
+            try {
+                const result = step.migrate(working);
+                if (result && typeof result === "object")
+                    working = result;
+                applied.push(step.version + ": " + step.describe);
+            } catch (error) {
+                // One bad migration must not cost the user every setting. Stop
+                // at the last good version so the next launch retries from
+                // here rather than skipping the failed step forever.
+                console.warn("Migrations: step", step.version, "failed:", error);
+                working[root.versionKey] = step.version - 1;
+                return { values: working, migrated: applied.length > 0, changed: applied.length > 0,
+                         from: from, to: step.version - 1, applied: applied };
+            }
+        }
+
+        working[root.versionKey] = current;
+        return { values: working, migrated: applied.length > 0, changed: from !== current,
+                 from: from, to: current, applied: applied };
+    }
+}

config/dot/quickshell/config/PreferenceSchema.qml

@@ -128,10 +128,21 @@ Singleton {
         {
             key: "vrrPolicy", type: "enum", def: 3, group: "display",
             label: "Variable refresh rate",
-            detail: "Content-aware matches the display to what is on screen",
+            detail: "Matches the display's refresh rate to what is on screen",
+            // All four the compositor publishes, rather than the two that were
+            // here. Always-on VRR is a legitimate choice on a panel that
+            // handles it well, and it was simply unreachable -- as was
+            // fullscreen-only, which is what someone wanting VRR for video
+            // rather than games wants.
             options: [
-                { value: 0, label: "Off" },
+                { value: 0, label: "Off",
-                { value: 3, label: "Content-aware" }
+                  detail: "The display runs at a fixed refresh rate" },
+                { value: 1, label: "Always on",
+                  detail: "Best on panels that handle low refresh rates without flicker" },
+                { value: 2, label: "Fullscreen only",
+                  detail: "Any fullscreen window, including video" },
+                { value: 3, label: "Fullscreen games",
+                  detail: "Only fullscreen games, which is the safest default" }
             ],
             hypr: { path: ["misc", "vrr"], option: "misc:vrr", readAs: "int" }
         },
@@ -140,8 +151,12 @@ Singleton {
             label: "Direct scanout",
             detail: "Lets fullscreen content bypass compositing",
             options: [
-                { value: 0, label: "Off" },
+                { value: 0, label: "Off",
-                { value: 2, label: "Automatic" }
+                  detail: "Everything goes through the compositor" },
+                { value: 1, label: "Always on",
+                  detail: "Forced rather than decided per surface; can drop frames on some drivers" },
+                { value: 2, label: "Automatic",
+                  detail: "The compositor decides per surface, which is the safe default" }
             ],
             hypr: { path: ["render", "direct_scanout"], option: "render:direct_scanout", readAs: "int" }
         },
@@ -299,12 +314,28 @@ Singleton {
         },
         {
             key: "followMouse", type: "enum", def: 1, group: "input",
-            label: "Focus follows pointer",
+            label: "Pointer focus",
-            detail: "Click to focus matches GNOME; sloppy focus follows the pointer",
+            detail: "What moving the pointer does to which window is focused",
+            // These labels were wrong, and wrong in the worst way: value 1 was
+            // shown as "Click to focus" while Hyprland's 1 means the opposite.
+            // The compositor publishes the authoritative mapping itself --
+            // `hyprctl descriptions` gives
+            //   map: [{"separate":3},{"detached":2},{"follow":1},{"disabled":0}]
+            // -- so a desktop labelled "Click to focus" was in fact following
+            // the pointer, and the way to actually get click-to-focus was to
+            // choose "Never". Value 3 was missing entirely.
+            //
+            // enum-hypr-map-contract now pins every mapped enum against that
+            // published map, so this cannot drift again.
             options: [
-                { value: 0, label: "Never" },
+                { value: 0, label: "Click to focus",
-                { value: 1, label: "Click to focus" },
+                  detail: "Moving the pointer never changes focus" },
-                { value: 2, label: "Sloppy focus" }
+                { value: 1, label: "Focus follows pointer",
+                  detail: "The window under the pointer takes focus as you move" },
+                { value: 2, label: "Pointer detached",
+                  detail: "The pointer highlights windows on its own; clicking moves keyboard focus" },
+                { value: 3, label: "Pointer fully separate",
+                  detail: "Clicking does not move keyboard focus at all" }
             ],
             hypr: { path: ["input", "follow_mouse"], option: "input:follow_mouse", readAs: "int" }
         },
@@ -489,6 +520,42 @@ Singleton {
             hypr: { path: ["misc", "mouse_move_focuses_monitor"], option: "misc:mouse_move_focuses_monitor", readAs: "bool" }
         },
 
+        // ── Accessibility ───────────────────────────────────────────────────
+        //
+        // Only what Hyprland can actually deliver. GNOME's sticky keys, slow
+        // keys, bounce keys and mouse keys are AccessX, an X11 server feature:
+        // XKB under Wayland has no accessx option group at all (verified
+        // against evdev.lst), and Hyprland does not implement it. The
+        // compositor will happily STORE "accessx:enable" as a keyboard option
+        // and nothing will ever act on it, which is exactly the kind of switch
+        // this app refuses to ship.
+        {
+            key: "magnifierFactor", type: "real", def: 1.0, min: 1.0, max: 5.0, step: 0.1,
+            group: "accessibility",
+            label: "Magnifier",
+            detail: "Magnifies the screen around the pointer. 1.0 is off",
+            hypr: { path: ["cursor", "zoom_factor"], option: "cursor:zoom_factor", readAs: "float" }
+        },
+        {
+            key: "magnifierRigid", type: "bool", def: false, group: "accessibility",
+            label: "Magnifier follows in steps",
+            detail: "Moves the magnified view in increments rather than gliding with the pointer",
+            hypr: { path: ["cursor", "zoom_rigid"], option: "cursor:zoom_rigid", readAs: "bool" }
+        },
+        {
+            key: "dimInactive", type: "bool", def: false, group: "accessibility",
+            label: "Dim inactive windows",
+            detail: "Darkens every window except the focused one, so the active window is unmistakable",
+            hypr: { path: ["decoration", "dim_inactive"], option: "decoration:dim_inactive", readAs: "bool" }
+        },
+        {
+            key: "dimStrength", type: "real", def: 0.5, min: 0.05, max: 0.9, step: 0.05,
+            group: "accessibility",
+            label: "Dim amount",
+            detail: "How much darker unfocused windows are",
+            hypr: { path: ["decoration", "dim_strength"], option: "decoration:dim_strength", readAs: "float" }
+        },
+
         // ── Night light ─────────────────────────────────────────────────────
         {
             key: "nightLightEnabled", type: "bool", def: false, group: "nightLight",

config/dot/quickshell/config/qmldir

@@ -4,3 +4,4 @@ singleton PreferenceSchema 1.0 PreferenceSchema.qml
 singleton HomePreferences 1.0 HomePreferences.qml
 singleton Settings 1.0 Settings.qml
 singleton Theme 1.0 Theme.qml
+singleton Migrations 1.0 Migrations.qml

config/dot/quickshell/health-harness.qml

@@ -0,0 +1,23 @@
+import Quickshell
+import Quickshell.Io
+import QtQuick
+
+import qs.services
+
+ShellRoot {
+    // The production singleton still performs its delayed startup scan. The
+    // harness turns it off before its 2200 ms deadline so each fixture drives
+    // only the state transition it is asserting.
+    Component.onCompleted: Health.startupScanEnabled = false
+
+    IpcHandler {
+        target: "health-test"
+
+        function accept(text: string, generation: int): bool { return Health.consumeSnapshot(text, generation); }
+        function queue(): void { Health.refresh(); Health.refresh(); }
+        function status(): string { return JSON.stringify(Health.diagnostics()); }
+        function repair(id: string): bool { return Health.repair(id, false); }
+        function report(): string { return JSON.stringify(Health.snapshot, null, 2); }
+        function copy(): bool { return Health.copyReport(); }
+    }
+}

config/dot/quickshell/migrations-harness.qml

@@ -0,0 +1,56 @@
+// Exercises Migrations.applyWith against fixture steps and prints a verdict per
+// case. Run by tests/quickshell/migrations-contract.sh.
+//
+// Fixture steps rather than the real list: the real one is empty until the
+// first breaking schema change, and a mechanism that has never been run against
+// a failing step is not one to discover the behaviour of during an upgrade.
+
+import Quickshell
+import QtQuick
+import qs.config
+
+ShellRoot {
+    Component.onCompleted: {
+        const steps = [
+            { version: 2, describe: "add b", migrate: v => { v.b = (v.a ?? 0) + 1; return v; } },
+            { version: 3, describe: "add c", migrate: v => { v.c = "three"; return v; } },
+            { version: 4, describe: "explode", migrate: v => { throw new Error("boom"); } }
+        ];
+        const results = {};
+
+        // No version at all: a file written before versioning. Stamped, never
+        // migrated.
+        let r = Migrations.applyWith({ a: 1 }, steps, 3, 1);
+        results.unversioned = { v: r.values.schemaVersion, migrated: r.migrated,
+                                changed: r.changed, untouched: r.values.b === undefined };
+
+        // Older file: every step above its version runs, in order.
+        r = Migrations.applyWith({ a: 1, schemaVersion: 1 }, steps, 3, 1);
+        results.upgrade = { v: r.values.schemaVersion, b: r.values.b, c: r.values.c,
+                            count: r.applied.length, migrated: r.migrated };
+
+        // Already current: nothing runs.
+        r = Migrations.applyWith({ schemaVersion: 3, keep: "me" }, steps, 3, 1);
+        results.current = { v: r.values.schemaVersion, migrated: r.migrated,
+                            kept: r.values.keep === "me", b: r.values.b === undefined };
+
+        // From the future: left completely alone, including its unknown keys.
+        r = Migrations.applyWith({ schemaVersion: 9, futureKey: "x" }, steps, 3, 1);
+        results.future = { v: r.values.schemaVersion, migrated: r.migrated,
+                           changed: r.changed, kept: r.values.futureKey === "x" };
+
+        // A failing step stops at the last good version rather than losing the
+        // file or skipping past the failure forever.
+        r = Migrations.applyWith({ schemaVersion: 1, a: 5 }, steps, 4, 1);
+        results.failure = { v: r.values.schemaVersion, b: r.values.b, c: r.values.c,
+                            kept: r.values.a === 5, count: r.applied.length };
+
+        // Unknown keys survive a migration: rolling back to an older Panama
+        // must not discard a newer version's settings.
+        r = Migrations.applyWith({ schemaVersion: 1, unknownFromFuture: true }, steps, 3, 1);
+        results.preserved = { kept: r.values.unknownFromFuture === true };
+
+        console.info("PANAMA-MIGRATIONS " + JSON.stringify(results));
+        Qt.callLater(() => Qt.quit());
+    }
+}

config/dot/quickshell/modules/bar/Bar.qml

@@ -108,6 +108,10 @@ PanelWindow {
                 anchors.verticalCenter: parent.verticalCenter
             }
 
+            HealthIndicator {
+                anchors.verticalCenter: parent.verticalCenter
+            }
+
             ActivityIndicator {
                 anchors.verticalCenter: parent.verticalCenter
             }

config/dot/quickshell/modules/bar/HealthIndicator.qml

@@ -0,0 +1,89 @@
+// A deliberately absent-until-needed health affordance. Healthy and merely
+// unconfigured systems leave no ornament or layout residue in the bar.
+
+import QtQuick
+import QtQuick.Controls
+import qs.config
+import qs.services
+
+Rectangle {
+    id: root
+
+    signal activated
+
+    readonly property int issueCount: Health.summary.warnings + Health.summary.errors
+    readonly property color tone: Health.status === "error"
+        ? Theme.danger
+        : (Health.status === "warning" ? Theme.warn : "transparent")
+    readonly property string statusText: root.issueCount === 1
+        ? "1 system health issue"
+        : root.issueCount + " system health issues"
+    readonly property string accessibleLabel: Health.status === "error"
+        ? "System Health: " + root.issueCount + (root.issueCount === 1 ? " issue requires action" : " issues require action")
+        : "System Health: " + root.issueCount + (root.issueCount === 1 ? " issue needs attention" : " issues need attention")
+    readonly property string tooltipText: root.accessibleLabel
+
+    visible: Health.actionable
+    implicitWidth: visible ? content.implicitWidth + 16 : 0
+    implicitHeight: visible ? 24 : 0
+    width: implicitWidth
+    height: implicitHeight
+    radius: 9
+    color: visible ? Theme.alpha(root.tone, 0.09) : "transparent"
+    border.width: activeFocus ? 2 : 1
+    border.color: visible ? Theme.alpha(root.tone, activeFocus ? 0.72 : 0.20) : "transparent"
+
+    activeFocusOnTab: visible
+    Accessible.role: Accessible.Button
+    Accessible.name: root.accessibleLabel
+    Accessible.description: "Open System Health"
+    Accessible.onPressAction: root.activated()
+
+    onActivated: {
+        ShellState.openSettings("services");
+        Health.refresh();
+    }
+
+    Keys.onReturnPressed: root.activated()
+    Keys.onEnterPressed: root.activated()
+    Keys.onSpacePressed: root.activated()
+
+    Row {
+        id: content
+
+        anchors.centerIn: parent
+        spacing: 6
+
+        Text {
+            anchors.verticalCenter: parent.verticalCenter
+            text: "\u{F0ECD}" // md-shield-alert-outline
+            color: root.tone
+            font.family: Theme.fontMono
+            font.pixelSize: 14
+        }
+
+        Text {
+            anchors.verticalCenter: parent.verticalCenter
+            text: String(root.issueCount)
+            color: root.tone
+            font.family: Theme.fontFamily
+            font.features: Theme.tabularFigures
+            font.pixelSize: Theme.fontSizeSmall
+            font.weight: Font.DemiBold
+        }
+    }
+
+    MouseArea {
+        id: pointer
+
+        anchors.fill: parent
+        enabled: root.visible
+        hoverEnabled: true
+        cursorShape: Qt.PointingHandCursor
+        onClicked: root.activated()
+    }
+
+    ToolTip.visible: pointer.containsMouse && root.visible
+    ToolTip.delay: 500
+    ToolTip.text: root.tooltipText
+}

config/dot/quickshell/modules/settings/AccessibilityPage.qml

@@ -37,20 +37,49 @@ SettingsPage {
         ToggleRow { setting: "animationsEnabled"; divider: false }
     }
 
+    // Zoom, done by the compositor rather than handed to GNOME. Hyprland has a
+    // real magnifier (cursor:zoom_factor) that follows the pointer, so there is
+    // no reason to send someone to another application for it.
     SettingsCard {
-        title: "Contrast"
+        title: "Magnifier"
-        subtitle: "Unfocused windows can be faded to make the focused one obvious, or left at full strength if that is harder to read."
+        subtitle: "Magnifies the screen around the pointer. Set the magnification to 1× to turn it off."
 
-        SliderRow { setting: "inactiveOpacity"; divider: false }
+        SliderRow { setting: "magnifierFactor"; zeroLabel: "Off" }
+        ToggleRow { setting: "magnifierRigid"; divider: false }
     }
 
     SettingsCard {
-        title: "System accessibility"
+        title: "Contrast"
-        subtitle: "Screen reader, zoom, and on-screen keyboard are provided by GNOME's accessibility stack."
+        subtitle: "Unfocused windows can be faded or darkened to make the focused one obvious, or left alone if that is harder to read."
+
+        SliderRow { setting: "inactiveOpacity" }
+        ToggleRow { setting: "dimInactive" }
+        SliderRow { setting: "dimStrength"; divider: false }
+    }
+
+    // What this session genuinely cannot do, said plainly.
+    //
+    // Sticky keys, slow keys, bounce keys and mouse keys are AccessX, which is
+    // an X11 SERVER feature. XKB under Wayland has no accessx option group at
+    // all, and Hyprland does not implement one. The compositor will accept
+    // "accessx:enable" as a keyboard option and store it, and nothing will ever
+    // act on it -- so there is no switch here, and pointing at GNOME's panel
+    // would be no better, since the daemon that applies those keys is not
+    // running either.
+    SettingsCard {
+        title: "Keyboard accessibility"
+        subtitle: "Sticky, slow and bounce keys are an X11 feature with no Wayland equivalent, so they are unavailable in this session. Offering them here would store a preference that nothing acts on."
+
+        ActionRow {
+            label: "Screen reader"
+            detail: "Orca reads the screen aloud and works over the accessibility bus, which does run here"
+            action: "Start Orca"
+            onTriggered: SystemSettings.openApplication("orca")
+        }
 
         ActionRow {
             label: "GNOME accessibility settings"
-            detail: "Opens in GNOME Settings"
+            detail: "For the parts GNOME's own stack still owns"
             action: "Open"
             divider: false
             onTriggered: SystemSettings.openGnomePanel("universal-access")

config/dot/quickshell/modules/settings/ConnectivityPage.qml

@@ -19,13 +19,18 @@ import qs.services
 SettingsPage {
     id: root
 
+
     title: "Network & Devices"
     lede: Connectivity.activeNetwork
         ? "Connected to " + Connectivity.activeNetwork.name
         : "Wi-Fi, Bluetooth, and the things Fedora owns."
 
     // Drive the scanners only while this page is the one being shown.
-    Component.onCompleted: Connectivity.active = true
+    Component.onCompleted: {
+        Connectivity.active = true;
+        if (!WifiShare.scanned)
+            WifiShare.refresh();
+    }
     Component.onDestruction: Connectivity.active = false
 
     SettingsCard {
@@ -68,6 +73,69 @@ SettingsPage {
         }
     }
 
+    // Sharing a network by QR, the way GNOME's Wi-Fi panel does. The
+    // alternative is reading a passphrase out loud.
+    //
+    // The image holds the password in machine-readable form, so it is generated
+    // on demand rather than up front, and the helper writes it to tmpfs under
+    // XDG_RUNTIME_DIR instead of anywhere persistent.
+    SettingsCard {
+        visible: Connectivity.wifiDevice !== null && WifiShare.shareable.length > 0
+        title: "Share a network"
+        subtitle: WifiShare.sharing !== ""
+            ? "Point a phone's camera at the code to join " + WifiShare.sharing + "."
+            : "Shows a QR code a phone can scan to join, without reading the password out."
+
+        Repeater {
+            model: WifiShare.shareable
+
+            ActionRow {
+                id: shareRow
+                required property var modelData
+                required property int index
+
+                label: shareRow.modelData.ssid
+                detail: WifiShare.sharing === shareRow.modelData.name
+                    ? "Showing a code below — anyone who can see the screen can join"
+                    : "Saved network"
+                action: WifiShare.sharing === shareRow.modelData.name ? "Hide" : "Show code"
+                divider: shareRow.index < WifiShare.shareable.length - 1 || WifiShare.sharing !== ""
+                onTriggered: WifiShare.sharing === shareRow.modelData.name
+                    ? WifiShare.stopSharing()
+                    : WifiShare.share(shareRow.modelData.name)
+            }
+        }
+
+        // Drawn at its natural size on a white plate: a QR code inverted or
+        // tinted to match a dark theme is unreliable to scan, and this one has
+        // exactly one job.
+        Item {
+            width: parent.width
+            visible: WifiShare.sharing !== "" && WifiShare.imagePath !== ""
+            implicitHeight: visible ? plate.height + 20 : 0
+
+            Rectangle {
+                id: plate
+                anchors.horizontalCenter: parent.horizontalCenter
+                y: 10
+                width: 208
+                height: 208
+                radius: 10
+                color: "white"
+
+                Image {
+                    anchors.centerIn: parent
+                    width: 184
+                    height: 184
+                    smooth: false
+                    fillMode: Image.PreserveAspectFit
+                    cache: false
+                    source: WifiShare.imagePath !== "" ? "file://" + WifiShare.imagePath : ""
+                }
+            }
+        }
+    }
+
     SettingsCard {
         title: "Bluetooth"
         visible: Connectivity.adapter !== null

config/dot/quickshell/modules/settings/HealthCheckRow.qml

@@ -0,0 +1,137 @@
+import QtQuick
+import qs.config
+import qs.services
+
+Item {
+    id: root
+
+    required property var check
+    property bool issue: false
+    property bool divider: true
+    property int actionActivationCount: 0
+    signal actionRequested(var check)
+
+    readonly property bool repairWorking: Health.repairingId === root.check.id
+    readonly property bool repairFailed: root.check.status !== "ok"
+        && Health.lastRepair.checkId === root.check.id
+        && (Health.lastRepair.accepted === false || Health.lastRepair.exitCode !== 0)
+
+    objectName: `health-check-row:${root.issue ? "issue" : "quiet"}:${root.check.id}`
+    implicitHeight: 62
+
+    // The isolated contract uses the same signal path as a pointer or keyboard
+    // activation instead of calling HealthPage's action handler directly.
+    function activateAction(): bool {
+        if (!actionButton.visible || !actionButton.enabled)
+            return false;
+        root.actionActivationCount += 1;
+        actionButton.clicked();
+        return true;
+    }
+
+    function statusLabel(status: string): string {
+        if (status === "ok") return "Healthy";
+        if (status === "warning") return "Needs attention";
+        if (status === "error") return "Action required";
+        return "Not set up";
+    }
+
+    function statusColor(status: string): color {
+        if (status === "ok") return Theme.ok;
+        if (status === "warning") return Theme.warn;
+        if (status === "error") return Theme.danger;
+        return Theme.fgMuted;
+    }
+
+    function displayedStatus(): string {
+        if (root.repairWorking)
+            return "Working…";
+        if (root.repairFailed)
+            return "Repair failed";
+        return root.statusLabel(root.check.status);
+    }
+
+    Rectangle {
+        id: issueMark
+
+        visible: root.issue
+        width: 7
+        height: 7
+        radius: 4
+        anchors.left: parent.left
+        anchors.leftMargin: 1
+        anchors.verticalCenter: parent.verticalCenter
+        color: root.statusColor(root.check.status)
+        border.width: 1
+        border.color: Theme.alpha(Theme.bgPanel, 0.9)
+    }
+
+    Column {
+        anchors.left: parent.left
+        anchors.leftMargin: root.issue ? 22 : 0
+        anchors.right: trailing.left
+        anchors.rightMargin: 16
+        anchors.verticalCenter: parent.verticalCenter
+        spacing: 3
+
+        Text {
+            width: parent.width
+            text: root.check.title
+            color: Theme.fg
+            font.family: Theme.fontFamily
+            font.pixelSize: Theme.fontSize
+            font.weight: Font.Medium
+            elide: Text.ElideRight
+        }
+
+        Text {
+            width: parent.width
+            text: root.check.detail
+            color: Theme.fgDim
+            font.family: Theme.fontFamily
+            font.pixelSize: Theme.fontSizeSmall
+            elide: Text.ElideRight
+        }
+    }
+
+    Row {
+        id: trailing
+
+        anchors.right: parent.right
+        anchors.verticalCenter: parent.verticalCenter
+        spacing: 12
+
+        Text {
+            objectName: `health-status-text:${root.issue ? "issue" : "quiet"}:${root.check.id}`
+            anchors.verticalCenter: parent.verticalCenter
+            text: root.displayedStatus()
+            color: root.statusColor(root.check.status)
+            font.family: Theme.fontFamily
+            font.pixelSize: Theme.fontSizeSmall
+        }
+
+        SettingsButton {
+            id: actionButton
+
+            objectName: `health-row-action:${root.issue ? "issue" : "quiet"}:${root.check.id}`
+            visible: root.check.action !== undefined
+            text: root.check.action?.label ?? ""
+            enabled: visible && !root.repairWorking && !Health.busy
+            activeFocusOnTab: enabled
+            border.width: activeFocus ? 2 : 1
+            border.color: activeFocus ? Theme.accent : Theme.alpha(Theme.fg, 0.08)
+            onClicked: root.actionRequested(root.check)
+            Keys.onReturnPressed: if (enabled) root.actionRequested(root.check)
+            Keys.onSpacePressed: if (enabled) root.actionRequested(root.check)
+        }
+    }
+
+    Rectangle {
+        visible: root.divider
+        anchors.left: parent.left
+        anchors.right: parent.right
+        anchors.bottom: parent.bottom
+        height: 1
+        color: Theme.alpha(Theme.fg, 0.07)
+    }
+}

config/dot/quickshell/modules/settings/HealthPage.qml

@@ -0,0 +1,458 @@
+import QtQuick
+import qs.config
+import qs.services
+
+SettingsPage {
+    id: root
+
+    objectName: "system-health-page"
+
+    title: "System Health"
+    lede: "Checks the parts of the desktop this app owns, and explains what needs attention."
+
+    property var pendingConfirmation: null
+    property string instructionTarget: ""
+
+    readonly property var issueChecks: Health.checks.filter(check => check.status === "warning" || check.status === "error")
+    readonly property var groups: [
+        {
+            group: "desktop-foundation",
+            title: "Desktop foundation",
+            subtitle: "Compositor, shell, portals, wallpaper, idle policy, and launcher."
+        },
+        {
+            group: "input-media",
+            title: "Input & media",
+            subtitle: "Sound, clipboard, capture, OCR, and display controls."
+        },
+        {
+            group: "integrations",
+            title: "Integrations",
+            subtitle: "Only configured integrations affect health."
+        },
+        {
+            group: "panama-tools",
+            title: "Desktop tools",
+            subtitle: "Tracked links, launcher commands, apps, and inhibitors."
+        }
+    ]
+    readonly property var applicationTargets: ({
+        "integration.nextcloud": "nextcloud",
+        "integration.rustdesk": "rustdesk",
+        "integration.kdeconnect": "kdeconnect",
+        "integration.bluebubbles": "bluebubbles"
+    })
+
+    function statusLabel(status: string): string {
+        if (status === "ok") return "Healthy";
+        if (status === "warning") return "Needs attention";
+        if (status === "error") return "Action required";
+        return "Not set up";
+    }
+
+    function checksForGroup(group: string): var {
+        return Health.checks.filter(check => check.group === group
+            && (check.status === "ok" || check.status === "unconfigured"));
+    }
+
+    function handleAction(check: var): void {
+        if (!check || !check.action)
+            return;
+
+        if (check.action.kind === "open") {
+            if (check.action.target) {
+                ShellState.openSettings(check.action.target);
+                return;
+            }
+            const application = root.applicationTargets[check.id];
+            if (application)
+                SystemSettings.openApplication(application);
+            return;
+        }
+
+        if (check.action.kind === "instructions") {
+            root.instructionTarget = check.action.target || "";
+            return;
+        }
+
+        if (check.action.kind !== "repair")
+            return;
+        if (check.action.confirm) {
+            root.pendingConfirmation = check;
+            return;
+        }
+        Health.repair(check.id, false);
+    }
+
+    function confirmRepair(): void {
+        const check = root.pendingConfirmation;
+        root.pendingConfirmation = null;
+        if (check)
+            Health.repair(check.id, false);
+    }
+
+    function descendants(item: var, prefix: string): var {
+        let matches = [];
+        if (!item)
+            return matches;
+        if (String(item.objectName || "").indexOf(prefix) === 0)
+            matches.push(item);
+        for (const child of item.children || [])
+            matches = matches.concat(root.descendants(child, prefix));
+        return matches;
+    }
+
+    function activateRenderedAction(id: string): bool {
+        const suffix = `:${id}`;
+        const rows = root.descendants(root, "health-check-row:").filter(row =>
+            row.visible && String(row.objectName).endsWith(suffix));
+        return rows.length === 1 && rows[0].activateAction();
+    }
+
+    function renderedFocusChain(): var {
+        // Repeater delegates enter Qt's tab chain lazily after their enabled
+        // binding changes at the end of a scan. Touch each rendered action's
+        // real next-focus link before traversing from the first hero control.
+        const renderedActions = root.descendants(root, "health-row-action:").filter(item =>
+            item.visible && item.enabled && item.activeFocusOnTab);
+        for (const action of renderedActions)
+            action.nextItemInFocusChain(true);
+
+        const starts = root.descendants(root, "health-copy-report-button").filter(item => item.visible && item.enabled);
+        if (starts.length !== 1)
+            return [];
+
+        const names = [];
+        const start = starts[0];
+        let current = start;
+        for (let index = 0; index < 128; index++) {
+            const name = String(current.objectName || "");
+            if (name !== "" && names.indexOf(name) < 0)
+                names.push(name);
+            current = current.nextItemInFocusChain(true);
+            if (!current || current === start)
+                break;
+        }
+        return names;
+    }
+
+    // Deterministic, read-only fixture seam used by the offscreen contract.
+    function uiDiagnostics(): var {
+        const summaries = root.descendants(root, "health-summary");
+        const rows = root.descendants(root, "health-check-row:").filter(row => row.visible);
+        const checkingLabels = root.descendants(root, "health-checking-label").filter(label => label.visible);
+        const confirmationSheets = root.descendants(root, "health-confirmation-sheet:").filter(sheet => sheet.visible);
+        const emptyGroups = root.descendants(root, "health-empty-group:").filter(label => label.visible);
+        const fedoraHandoffs = root.descendants(root, "health-fedora-handoff:").filter(row => row.visible);
+        return {
+            renderedRows: rows.map(row => {
+                const objectName = String(row.objectName);
+                const parts = objectName.split(":");
+                const statusTexts = root.descendants(row, "health-status-text:").filter(text => text.visible);
+                return {
+                    objectName: objectName,
+                    id: parts.slice(2).join(":"),
+                    section: parts[1],
+                    statusText: statusTexts.length === 1 ? statusTexts[0].text : ""
+                };
+            }),
+            summaryHeight: summaries.length > 0 ? summaries[0].height : 0,
+            rowHeights: rows.map(row => row.height),
+            checking: Health.busy,
+            checkingText: checkingLabels.length > 0 ? checkingLabels[0].text : "",
+            focusChain: root.renderedFocusChain(),
+            activatedRows: rows.filter(row => row.actionActivationCount > 0).map(row => String(row.objectName)),
+            emptyQuietGroups: emptyGroups.map(label => String(label.objectName).slice("health-empty-group:".length)),
+            fedoraHandoffs: fedoraHandoffs.map(row => ({
+                id: String(row.objectName).slice("health-fedora-handoff:".length),
+                label: row.label,
+                action: row.action
+            })),
+            confirmationVisible: confirmationSheets.length === 1,
+            confirmationId: confirmationSheets.length === 1
+                ? String(confirmationSheets[0].objectName).slice("health-confirmation-sheet:".length)
+                : ""
+        };
+    }
+
+    Component.onCompleted: Health.refresh()
+
+    header: Component {
+        Rectangle {
+            objectName: `health-confirmation-sheet:${root.pendingConfirmation ? root.pendingConfirmation.id : ""}`
+            visible: root.pendingConfirmation !== null
+            implicitHeight: visible ? confirmRow.implicitHeight + 28 : 0
+            radius: Theme.cardRadius
+            color: Theme.mix(Theme.bgPanel, Theme.warn, 0.1)
+            border.width: 1
+            border.color: Theme.alpha(Theme.warn, 0.34)
+
+            Row {
+                id: confirmRow
+                anchors.left: parent.left
+                anchors.right: parent.right
+                anchors.verticalCenter: parent.verticalCenter
+                anchors.margins: 16
+                spacing: 14
+
+                Column {
+                    width: parent.width - cancelButton.width - repairButton.width - 28
+                    anchors.verticalCenter: parent.verticalCenter
+                    spacing: 3
+
+                    Text {
+                        width: parent.width
+                        text: root.pendingConfirmation
+                            ? `${root.pendingConfirmation.action.label}?`
+                            : "Restart the shell?"
+                        color: Theme.fg
+                        font.family: Theme.fontFamily
+                        font.pixelSize: Theme.fontSize
+                        font.weight: Font.DemiBold
+                    }
+
+                    Text {
+                        width: parent.width
+                        text: "The desktop chrome will disappear briefly and return when Quickshell restarts."
+                        color: Theme.fgDim
+                        font.family: Theme.fontFamily
+                        font.pixelSize: Theme.fontSizeSmall
+                        wrapMode: Text.WordWrap
+                    }
+                }
+
+                SettingsButton {
+                    id: cancelButton
+                    text: "Cancel"
+                    activeFocusOnTab: true
+                    border.width: activeFocus ? 2 : 1
+                    border.color: activeFocus ? Theme.accent : Theme.alpha(Theme.fg, 0.08)
+                    onClicked: root.pendingConfirmation = null
+                    Keys.onReturnPressed: root.pendingConfirmation = null
+                    Keys.onSpacePressed: root.pendingConfirmation = null
+                }
+
+                SettingsButton {
+                    id: repairButton
+                    text: root.pendingConfirmation ? root.pendingConfirmation.action.label : "Restart the shell"
+                    activeFocusOnTab: true
+                    border.width: activeFocus ? 2 : 1
+                    border.color: activeFocus ? Theme.accent : Theme.alpha(Theme.fg, 0.08)
+                    onClicked: root.confirmRepair()
+                    Keys.onReturnPressed: root.confirmRepair()
+                    Keys.onSpacePressed: root.confirmRepair()
+                }
+            }
+        }
+    }
+
+    HealthSummary {}
+
+    SettingsCard {
+        visible: root.issueChecks.length > 0
+        title: Health.status === "error" ? "Action required" : "Needs attention"
+        subtitle: Health.status === "error"
+            ? "Resolve these items first. Healthy systems remain listed below."
+            : "Nothing here prevents you from using the desktop."
+
+        Item {
+            width: parent.width
+            implicitHeight: issueRows.implicitHeight
+
+            Rectangle {
+                anchors.left: parent.left
+                anchors.leftMargin: 4
+                anchors.top: parent.top
+                anchors.topMargin: 25
+                anchors.bottom: parent.bottom
+                anchors.bottomMargin: 25
+                width: 1
+                visible: root.issueChecks.length > 1
+                color: Theme.alpha(Health.status === "error" ? Theme.danger : Theme.warn, 0.44)
+            }
+
+            Column {
+                id: issueRows
+                width: parent.width
+
+                Repeater {
+                    id: issueRepeater
+                    model: root.issueChecks
+
+                    HealthCheckRow {
+                        required property var modelData
+                        required property int index
+
+                        width: issueRows.width
+                        check: modelData
+                        issue: true
+                        divider: index < issueRepeater.count - 1
+                        onActionRequested: check => root.handleAction(check)
+                    }
+                }
+            }
+        }
+    }
+
+    SettingsCard {
+        visible: root.instructionTarget === "ddc-permissions"
+        title: "External monitor brightness"
+        subtitle: "The monitor reports DDC/CI support, but this session cannot reach the monitor bus."
+
+        Item {
+            width: parent.width
+            implicitHeight: Math.max(instructionCopy.implicitHeight, doneButton.implicitHeight) + 8
+
+            Text {
+                id: instructionCopy
+                anchors.left: parent.left
+                anchors.right: doneButton.left
+                anchors.rightMargin: 18
+                anchors.verticalCenter: parent.verticalCenter
+                text: "Reload the installed udev rules and trigger the i2c-dev and DRM devices. Sign out and back in if monitor access is still unavailable."
+                color: Theme.fgDim
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeSmall
+                wrapMode: Text.WordWrap
+            }
+
+            SettingsButton {
+                id: doneButton
+                anchors.right: parent.right
+                anchors.verticalCenter: parent.verticalCenter
+                text: "Done"
+                activeFocusOnTab: true
+                border.width: activeFocus ? 2 : 1
+                border.color: activeFocus ? Theme.accent : Theme.alpha(Theme.fg, 0.08)
+                onClicked: root.instructionTarget = ""
+                Keys.onReturnPressed: root.instructionTarget = ""
+                Keys.onSpacePressed: root.instructionTarget = ""
+            }
+        }
+    }
+
+    Grid {
+        id: groupGrid
+
+        width: parent.width
+        columns: width >= 700 ? 2 : 1
+        columnSpacing: 16
+        rowSpacing: 16
+
+        Repeater {
+            model: root.groups
+
+            SettingsCard {
+                required property var modelData
+                readonly property var quietChecks: root.checksForGroup(modelData.group)
+
+                width: groupGrid.columns === 2
+                    ? (groupGrid.width - groupGrid.columnSpacing) / 2
+                    : groupGrid.width
+                title: modelData.title
+                subtitle: modelData.subtitle
+
+                Column {
+                    id: groupRows
+                    width: parent.width
+
+                    Text {
+                        objectName: `health-empty-group:${modelData.group}`
+                        width: parent.width
+                        visible: quietChecks.length === 0
+                        text: "Items needing attention are listed above."
+                        color: Theme.fgMuted
+                        font.family: Theme.fontFamily
+                        font.pixelSize: Theme.fontSizeSmall
+                        topPadding: 8
+                        bottomPadding: 8
+                        wrapMode: Text.WordWrap
+                    }
+
+                    Repeater {
+                        id: groupRepeater
+                        model: quietChecks
+
+                        HealthCheckRow {
+                            required property var modelData
+                            required property int index
+
+                            width: groupRows.width
+                            check: modelData
+                            divider: index < groupRepeater.count - 1
+                            onActionRequested: check => root.handleAction(check)
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    SettingsCard {
+        title: "Fedora system settings"
+        subtitle: "These areas remain owned by Fedora and GNOME's mature system panels."
+
+        Item {
+            width: parent.width
+            implicitHeight: 42
+
+            Text {
+                anchors.left: parent.left
+                anchors.right: gnomeSettingsButton.left
+                anchors.rightMargin: 18
+                anchors.verticalCenter: parent.verticalCenter
+                text: "Use GNOME Settings for the parts of the system this app does not manage."
+                color: Theme.fgDim
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeSmall
+                wrapMode: Text.WordWrap
+            }
+
+            SettingsButton {
+                id: gnomeSettingsButton
+                anchors.right: parent.right
+                anchors.verticalCenter: parent.verticalCenter
+                text: "Open GNOME Settings"
+                activeFocusOnTab: true
+                border.width: activeFocus ? 2 : 1
+                border.color: activeFocus ? Theme.accent : Theme.alpha(Theme.fg, 0.08)
+                onClicked: SystemSettings.openGnomePanel("network")
+                Keys.onReturnPressed: SystemSettings.openGnomePanel("network")
+                Keys.onSpacePressed: SystemSettings.openGnomePanel("network")
+            }
+        }
+
+        ActionRow {
+            objectName: "health-fedora-handoff:users"
+            label: "Users"
+            detail: "Accounts, passwords, and automatic login"
+            action: "Open users"
+            onTriggered: SystemSettings.openGnomePanel("system", "users")
+        }
+
+        ActionRow {
+            objectName: "health-fedora-handoff:sharing"
+            label: "Sharing"
+            detail: "Remote desktop, media sharing, and remote login"
+            action: "Open sharing"
+            onTriggered: SystemSettings.openGnomePanel("sharing")
+        }
+
+        ActionRow {
+            objectName: "health-fedora-handoff:color"
+            label: "Colour profiles"
+            detail: "ICC profiles for displays, printers, and scanners"
+            action: "Open colour"
+            onTriggered: SystemSettings.openGnomePanel("color")
+        }
+
+        ActionRow {
+            objectName: "health-fedora-handoff:wellbeing"
+            label: "Digital wellbeing"
+            detail: "Screen time and break reminders"
+            action: "Open wellbeing"
+            divider: false
+            onTriggered: SystemSettings.openGnomePanel("wellbeing")
+        }
+    }
+}

config/dot/quickshell/modules/settings/HealthSummary.qml

@@ -0,0 +1,169 @@
+import QtQuick
+import qs.config
+import qs.services
+
+SettingsCard {
+    id: root
+
+    objectName: "health-summary"
+    implicitHeight: 126
+
+    readonly property int observationCount: Health.summary.warnings + Health.summary.errors
+    readonly property string heroTitle: {
+        if (Health.diagnosticUnavailable)
+            return "Health check unavailable";
+        if (Health.checks.length === 0)
+            return "Checking the desktop";
+        if (Health.status === "error")
+            return "Action required";
+        if (Health.status === "warning")
+            return "Needs attention";
+        return "Healthy";
+    }
+    readonly property string heroDetail: {
+        if (Health.diagnosticUnavailable)
+            return Health.lastError || "The latest health check could not be completed.";
+        if (Health.checks.length === 0)
+            return "Checking the desktop services, tools, and integrations this app owns.";
+        if (Health.status === "error")
+            return root.observationCount === 1
+                ? "One part of the desktop needs action."
+                : `${root.observationCount} parts of the desktop need action.`;
+        if (Health.status === "warning")
+            return root.observationCount === 1
+                ? "Your desktop is working. One feature needs a decision."
+                : `Your desktop is working. ${root.observationCount} features need a decision.`;
+        return "Desktop services and tools are working normally.";
+    }
+    readonly property color statusColor: {
+        if (Health.diagnosticUnavailable || Health.status === "error")
+            return Theme.danger;
+        if (Health.status === "warning")
+            return Theme.warn;
+        if (Health.checks.length === 0)
+            return Theme.fgMuted;
+        return Theme.ok;
+    }
+
+    function scanTime(): string {
+        const generatedAt = String(Health.snapshot.generatedAt || "");
+        if (generatedAt === "")
+            return "No completed check yet";
+        const date = new Date(generatedAt);
+        if (Number.isNaN(date.getTime()))
+            return "Last check completed";
+        return `Last checked ${date.toLocaleTimeString(Qt.locale(), Locale.ShortFormat)}`;
+    }
+
+    Item {
+        width: parent.width
+        implicitHeight: 96
+
+        Column {
+            anchors.left: parent.left
+            anchors.right: actions.left
+            anchors.rightMargin: 22
+            anchors.verticalCenter: parent.verticalCenter
+            spacing: 4
+
+            Text {
+                width: parent.width
+                text: Health.diagnosticUnavailable
+                    ? "DIAGNOSTICS"
+                    : root.observationCount > 0
+                        ? root.observationCount + (root.observationCount === 1 ? " OBSERVATION" : " OBSERVATIONS")
+                        : "PANAMA DESKTOP"
+                color: root.statusColor
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeSmall
+                font.weight: Font.DemiBold
+                font.letterSpacing: 1.15
+            }
+
+            Text {
+                width: parent.width
+                text: root.heroTitle
+                color: Theme.fg
+                font.family: Theme.fontFamily
+                font.pixelSize: 24
+                font.weight: Font.DemiBold
+                elide: Text.ElideRight
+            }
+
+            Text {
+                width: parent.width
+                text: root.heroDetail
+                color: Theme.fgDim
+                font.family: Theme.fontFamily
+                font.pixelSize: Theme.fontSizeSmall
+                elide: Text.ElideRight
+            }
+
+            Row {
+                spacing: 10
+
+                Text {
+                    text: root.scanTime()
+                    color: Theme.fgMuted
+                    font.family: Theme.fontFamily
+                    font.pixelSize: Theme.fontSizeSmall
+                }
+
+                Text {
+                    objectName: "health-checking-label"
+                    visible: Health.busy
+                    text: "Checking…"
+                    color: Theme.fgDim
+                    font.family: Theme.fontFamily
+                    font.pixelSize: Theme.fontSizeSmall
+                }
+
+                Text {
+                    visible: Health.lastCopyResult !== ""
+                    text: Health.lastCopyResult
+                    color: Health.lastCopyResult === "Report copied." ? Theme.ok : Theme.warn
+                    font.family: Theme.fontFamily
+                    font.pixelSize: Theme.fontSizeSmall
+                }
+            }
+        }
+
+        Row {
+            id: actions
+
+            anchors.right: parent.right
+            anchors.verticalCenter: parent.verticalCenter
+            spacing: 8
+
+            SettingsButton {
+                id: copyButton
+
+                objectName: "health-copy-report-button"
+                visible: !Health.diagnosticUnavailable
+                text: "Copy report"
+                enabled: Health.checks.length > 0
+                activeFocusOnTab: enabled
+                border.width: activeFocus ? 2 : 1
+                border.color: activeFocus ? Theme.accent : Theme.alpha(Theme.fg, 0.08)
+                onClicked: Health.copyReport()
+                Keys.onReturnPressed: if (enabled) Health.copyReport()
+                Keys.onSpacePressed: if (enabled) Health.copyReport()
+            }
+
+            SettingsButton {
+                id: refreshButton
+
+                objectName: "health-refresh-button"
+                text: Health.diagnosticUnavailable ? "Retry" : "Refresh"
+                tone: Health.diagnosticUnavailable ? "normal" : "accent"
+                enabled: !Health.busy
+                activeFocusOnTab: enabled
+                border.width: activeFocus ? 2 : (tone === "accent" ? 0 : 1)
+                border.color: activeFocus ? Theme.accent : Theme.alpha(Theme.fg, 0.08)
+                onClicked: Health.refresh()
+                Keys.onReturnPressed: if (enabled) Health.refresh()
+                Keys.onSpacePressed: if (enabled) Health.refresh()
+            }
+        }
+    }
+}

config/dot/quickshell/modules/settings/PowerPage.qml

@@ -14,9 +14,43 @@ import qs.services
 SettingsPage {
     id: root
 
+    // Probing the power daemon is a D-Bus round trip, so it happens when the
+    // page opens rather than at shell startup.
+    Component.onCompleted: if (!PowerProfiles.scanned) PowerProfiles.refresh()
+
     title: "Power & Lock"
     lede: "When the screen turns off, when the session locks, and whether it ever sleeps."
 
+    // The same profiles GNOME's Power panel offers. Not a stored preference --
+    // the daemon owns it, it survives Panama restarts, and anything else on the
+    // system can change it, so a copy here would drift.
+    SettingsCard {
+        visible: PowerProfiles.available || PowerProfiles.lastError !== ""
+        title: "Power profile"
+        subtitle: PowerProfiles.degraded !== ""
+            ? "Performance is limited right now: " + PowerProfiles.degraded
+            : (PowerProfiles.available
+                ? "Applies to the whole system and persists across sessions."
+                : PowerProfiles.lastError)
+
+        Repeater {
+            model: PowerProfiles.profiles
+
+            SettingRow {
+                id: profileRow
+                required property var modelData
+                required property int index
+
+                label: PowerProfiles.label(profileRow.modelData)
+                detail: PowerProfiles.detail(profileRow.modelData)
+                value: profileRow.modelData === PowerProfiles.active ? "Active" : ""
+                divider: profileRow.index < PowerProfiles.profiles.length - 1
+                activatable: profileRow.modelData !== PowerProfiles.active && !PowerProfiles.busy
+                onActivated: PowerProfiles.set(profileRow.modelData)
+            }
+        }
+    }
+
     SettingsCard {
         title: "Idle behaviour"
         subtitle: IdleLock.managed

config/dot/quickshell/modules/settings/README.md

@@ -4,6 +4,33 @@ The control centre for everything Panama owns. Anything the system owns —
 hardware, accounts, printers — is delegated to GNOME Settings and labelled as
 such rather than half-reimplemented.
 
+## System Health
+
+The stable internal `services` route renders **System Health**. It is reachable
+from the Settings sidebar and its live 54px footer, the degraded-only bar
+indicator, and Vicinae's **Panama: Check System Health** command. Healthy scans
+reserve no bar space and produce no notification.
+
+`services/Health.qml` owns the last accepted redacted snapshot. It invokes
+`scripts/panama-doctor` for scans and bounded repairs, `wl-copy` only for an
+explicit **Copy Report**, and bounded `notify-send` only when an external repair
+fails. For a concise terminal view, run:
+
+```bash
+~/.config/quickshell/scripts/panama-doctor --summary
+```
+
+The helper diagnoses Panama-owned desktop services, dependencies, links, and
+configured integrations. It does not read secret values, clipboard or
+notification contents, calendar events, SSIDs, addresses, or arbitrary command
+output. Its repair interface is an authored allow-list: it never installs a
+package, runs `sudo`, deletes user data, or repairs a service Panama does not
+own. A repair remains degraded until a fresh scan observes recovery.
+
+The final card is the ownership boundary. Network configuration and the exact
+Users, Sharing, Colour profiles, and Digital wellbeing handoffs open GNOME
+Settings because Fedora's system services own those areas.
+
 ## Adding a setting
 
 One schema entry. That is the whole job.
@@ -83,11 +110,12 @@ slot**, because that is the row's default property, so only the right-hand edge
 becomes clickable. Use `activatable: true` with `onActivated` for a whole-row
 target.
 
-**A copy of the Quickshell config shares the live shell's ID.** Quickshell
+**A content-identical Quickshell entry can share the live shell's ID.**
-derives the Shell ID from config *content*, not path, so
+Quickshell derives the Shell ID from config *content*, not path. Runtime
-`cp -a config/dot/quickshell $tmp && qs -p $tmp kill` kills the running
+harnesses therefore create a distinct semantic entry file, address that exact
-desktop, and `qs -p $tmp ipc call …` can drive it. Harnesses that point at a
+file with `qs -p`, and discover its PID from the exact Config path in
-single distinct `.qml` file are safe; copying the whole directory is not.
+`qs list --all`. They terminate only that recorded PID with `kill`; never use
+`qs kill` from a copied configuration.
 
 ## Where state lives
 

config/dot/quickshell/modules/settings/ServicesPage.qml

@@ -1,159 +0,0 @@
-import QtQuick
-import qs.config
-import qs.services
-
-SettingsPage {
-    title: "Startup & Services"
-    lede: "A clear view of the background tools that make the desktop feel complete."
-
-    function status(active: bool): string {
-        return active ? "Running" : "Stopped";
-    }
-
-    Item {
-        width: parent.width
-        implicitHeight: refresh.implicitHeight
-
-        SettingsButton {
-            id: refresh
-            anchors.right: parent.right
-            text: SystemSettings.busy ? "Refreshing…" : "Refresh"
-            enabled: !SystemSettings.busy
-            onClicked: SystemSettings.refresh()
-        }
-    }
-
-    SettingsCard {
-        title: "Your services"
-
-        SettingRow {
-            label: "Nextcloud"
-            detail: "File synchronization and tray status"
-            controlWidth: 190
-
-            Row {
-                anchors.right: parent.right
-                anchors.verticalCenter: parent.verticalCenter
-                spacing: 10
-                Text {
-                    anchors.verticalCenter: parent.verticalCenter
-                    text: status(SystemSettings.nextcloudActive)
-                    color: Theme.fgDim
-                    font.family: Theme.fontFamily
-                    font.pixelSize: Theme.fontSize
-                }
-                SettingsButton {
-                    text: "Open"
-                    onClicked: SystemSettings.openApplication("nextcloud")
-                }
-            }
-        }
-
-        SettingRow {
-            label: "RustDesk"
-            detail: "Remote access through the enabled system service"
-            controlWidth: 190
-
-            Row {
-                anchors.right: parent.right
-                anchors.verticalCenter: parent.verticalCenter
-                spacing: 10
-                Text {
-                    anchors.verticalCenter: parent.verticalCenter
-                    text: status(SystemSettings.rustdeskActive)
-                    color: Theme.fgDim
-                    font.family: Theme.fontFamily
-                    font.pixelSize: Theme.fontSize
-                }
-                SettingsButton {
-                    text: "Open"
-                    onClicked: SystemSettings.openApplication("rustdesk")
-                }
-            }
-        }
-
-        SettingRow {
-            label: "KDE Connect"
-            detail: "Phone pairing, clipboard, files, and remote controls"
-            divider: false
-            controlWidth: 190
-
-            Row {
-                anchors.right: parent.right
-                anchors.verticalCenter: parent.verticalCenter
-                spacing: 10
-                Text {
-                    anchors.verticalCenter: parent.verticalCenter
-                    text: status(SystemSettings.kdeconnectActive)
-                    color: Theme.fgDim
-                    font.family: Theme.fontFamily
-                    font.pixelSize: Theme.fontSize
-                }
-                SettingsButton {
-                    text: "Open"
-                    onClicked: SystemSettings.openApplication("kdeconnect")
-                }
-            }
-        }
-    }
-
-    SettingsCard {
-        title: "Desktop foundation"
-
-        TextRow {
-            label: "Hyprpaper"
-            detail: "Wallpaper service"
-            value: status(SystemSettings.hyprpaperActive)
-        }
-        TextRow {
-            label: "Hypridle"
-            detail: "Idle and lock policy"
-            value: status(SystemSettings.hypridleActive)
-        }
-        TextRow {
-            label: "Vicinae"
-            detail: "Spotlight-style launcher daemon"
-            value: status(SystemSettings.vicinaeActive)
-            divider: false
-        }
-    }
-
-    SettingsCard {
-        title: "Fedora system settings"
-        subtitle: "Panels this app does not own, because they configure system services rather than the desktop. Each row opens the panel that actually owns it. Printers and online accounts live with the rest of the network hardware, on Network & Devices."
-
-        // This was one row listing five subjects and opening the network panel
-        // regardless. Naming a panel and then not opening it is worse than not
-        // offering it: it looks like a broken button rather than a deliberate
-        // hand-off, and someone looking for printers had to know to navigate
-        // once GNOME Settings appeared on the wrong page.
-        ActionRow {
-            label: "Users"
-            detail: "Accounts, passwords, and automatic login"
-            action: "Open users"
-            onTriggered: SystemSettings.openGnomePanel("system", "users")
-        }
-
-        ActionRow {
-            label: "Sharing"
-            detail: "Remote desktop, media sharing, and remote login"
-            action: "Open sharing"
-            onTriggered: SystemSettings.openGnomePanel("sharing")
-        }
-
-        ActionRow {
-            label: "Colour profiles"
-            detail: "ICC profiles for displays, printers, and scanners"
-            action: "Open colour"
-            onTriggered: SystemSettings.openGnomePanel("color")
-        }
-
-        ActionRow {
-            label: "Digital wellbeing"
-            detail: "Screen time and break reminders"
-            action: "Open wellbeing"
-            divider: false
-            onTriggered: SystemSettings.openGnomePanel("wellbeing")
-        }
-    }
-}

config/dot/quickshell/modules/settings/SettingsShell.qml

@@ -11,6 +11,19 @@ Rectangle {
         && pageLoader.item.objectName === "home-phone-page"
         ? pageLoader.item.pageDiagnostics
         : ({})
+    readonly property var healthDiagnostics: pageLoader.status === Loader.Ready
+        && pageLoader.item
+        && pageLoader.item.objectName === "system-health-page"
+        ? pageLoader.item.uiDiagnostics()
+        : ({})
+
+    function requestHealthAction(id: string): bool {
+        if (pageLoader.status !== Loader.Ready
+                || !pageLoader.item
+                || pageLoader.item.objectName !== "system-health-page")
+            return false;
+        return pageLoader.item.activateRenderedAction(id);
+    }
 
     color: Theme.bg
     radius: 18
@@ -107,7 +120,7 @@ Rectangle {
             case "power": return powerPage;
             case "datetime": return dateTimePage;
             case "applications": return applicationsPage;
-            case "services": return servicesPage;
+            case "services": return healthPage;
             case "about": return aboutPage;
             default: return homePage;
             }
@@ -161,7 +174,7 @@ Rectangle {
     Component { id: privacyPage; PrivacyPage {} }
     Component { id: regionPage; RegionPage {} }
     Component { id: onlineAccountsPage; OnlineAccountsPage {} }
-    Component { id: servicesPage; ServicesPage {} }
+    Component { id: healthPage; HealthPage {} }
     Component { id: aboutPage; AboutPage {} }
 
     Shortcut {

config/dot/quickshell/modules/settings/SettingsSidebar.qml

@@ -40,7 +40,7 @@ Rectangle {
         { page: "power", label: "Power & Lock", icon: "\u{F0425}" },
         { page: "datetime", label: "Date & Time", icon: "\u{F0954}" },
         { page: "applications", label: "Applications", icon: "\u{F003B}" },
-        { page: "services", label: "Startup & Services", icon: "\u{F0493}" },
+        { page: "services", label: "System Health", icon: "\u{F0493}" },
         { page: "about", label: "About", icon: "\u{F02FD}" }
     ]
 
@@ -292,8 +292,34 @@ Rectangle {
         anchors.right: parent.right
         anchors.bottom: parent.bottom
         height: 54
-        color: Theme.alpha(Theme.bg, 0.35)
+        activeFocusOnTab: true
-        border.width: 0
+        color: footerTap.hovered || activeFocus
+            ? Theme.alpha(Theme.fg, 0.07)
+            : Theme.alpha(Theme.bg, 0.35)
+        border.width: activeFocus ? 2 : 0
+        border.color: Theme.accent
+
+        function footerText(): string {
+            if (Health.checks.length === 0)
+                return Health.diagnosticUnavailable ? "Health check unavailable" : "Checking the desktop";
+            if (Health.status === "error")
+                return "Desktop needs attention";
+            if (Health.status === "warning") {
+                const count = Health.summary.warnings + Health.summary.errors;
+                return count + (count === 1 ? " health observation" : " health observations");
+            }
+            return "Desktop is healthy";
+        }
+
+        function footerColor(): color {
+            if (Health.checks.length === 0)
+                return Health.diagnosticUnavailable ? Theme.danger : Theme.fgMuted;
+            if (Health.status === "error")
+                return Theme.danger;
+            if (Health.status === "warning")
+                return Theme.warn;
+            return Theme.ok;
+        }
 
         Rectangle {
             width: 7
@@ -302,17 +328,28 @@ Rectangle {
             anchors.left: parent.left
             anchors.leftMargin: 19
             anchors.verticalCenter: parent.verticalCenter
-            color: Theme.ok
+            color: healthFooter.footerColor()
         }
 
         Text {
             anchors.left: parent.left
             anchors.leftMargin: 36
+            anchors.right: parent.right
+            anchors.rightMargin: 12
             anchors.verticalCenter: parent.verticalCenter
-            text: "Desktop is healthy"
+            text: healthFooter.footerText()
             color: Theme.fgDim
             font.family: Theme.fontFamily
             font.pixelSize: Theme.fontSizeSmall
+            elide: Text.ElideRight
         }
+
+        TapHandler {
+            id: footerTap
+            onTapped: root.pageRequested("services")
+        }
+
+        Keys.onReturnPressed: root.pageRequested("services")
+        Keys.onSpacePressed: root.pageRequested("services")
     }
 }

config/dot/quickshell/modules/settings/qmldir

@@ -10,7 +10,9 @@ DisplaysPage 1.0 DisplaysPage.qml
 HomePage 1.0 HomePage.qml
 NotificationsPage 1.0 NotificationsPage.qml
 ScreenIntelligencePage 1.0 ScreenIntelligencePage.qml
-ServicesPage 1.0 ServicesPage.qml
+HealthPage 1.0 HealthPage.qml
+HealthSummary 1.0 HealthSummary.qml
+HealthCheckRow 1.0 HealthCheckRow.qml
 SettingRow 1.0 SettingRow.qml
 SettingsCard 1.0 SettingsCard.qml
 SettingsButton 1.0 SettingsButton.qml

config/dot/quickshell/scripts/panama-action

@@ -109,6 +109,7 @@ case "$action" in
     clipboard) qs ipc call clipboard open ;;
     overview) qs ipc call overview open ;;
     settings) qs ipc call settings open ;;
+    health) qs ipc call health open ;;
 
     dnd)
         state="$(qs ipc call notifications dnd)"
@@ -148,7 +149,7 @@ case "$action" in
         ;;
     *)
         printf 'Usage: panama-action {%s}\n' \
-            'control-center|notifications|calendar|clipboard|overview|settings|dnd|caffeine|night-light|focus-start|focus-end|capture|intelligence|screenshot|microphone|gallery|restart-shell' >&2
+            'control-center|notifications|calendar|clipboard|overview|settings|health|dnd|caffeine|night-light|focus-start|focus-end|capture|intelligence|screenshot|microphone|gallery|restart-shell' >&2
         exit 2
         ;;
 esac

config/dot/quickshell/scripts/panama-doctor

@@ -0,0 +1,859 @@
+#!/usr/bin/env python3
+
+"""Redacted diagnostics and bounded repairs for Panama-owned functionality."""
+
+from __future__ import annotations
+
+import argparse
+import ctypes
+import errno
+import json
+import os
+import re
+import secrets
+import signal
+import shutil
+import subprocess
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from types import MappingProxyType
+from typing import Callable, Literal
+
+Status = Literal["ok", "warning", "error", "unconfigured"]
+Group = Literal["desktop-foundation", "input-media", "integrations", "panama-tools"]
+ActionKind = Literal["repair", "open", "instructions"]
+InhibitorRow = tuple[str, str, str, str, str, str, str, str]
+
+AT_FDCWD = -100
+RENAME_NOREPLACE = 1
+RENAME_EXCHANGE = 2
+
+
+@dataclass(frozen=True)
+class Action:
+    kind: ActionKind
+    label: str
+    confirm: bool = False
+    # Only authored Settings page IDs and instruction IDs are allowed here.
+    # Repair commands never receive a caller-controlled target.
+    target: str | None = None
+
+
+@dataclass(frozen=True)
+class Check:
+    id: str
+    group: Group
+    title: str
+    status: Status
+    detail: str
+    action: Action | None = None
+
+
+@dataclass(frozen=True)
+class DoctorConfig:
+    root: Path
+    home: Path
+    config_home: Path
+    state_home: Path
+    runtime_dir: Path
+    path: str
+    timeout: float
+
+    @property
+    def command_env(self) -> dict[str, str]:
+        environment = {
+            "PATH": self.path,
+            "HOME": str(self.home),
+            "XDG_CONFIG_HOME": str(self.config_home),
+            "XDG_STATE_HOME": str(self.state_home),
+            "XDG_RUNTIME_DIR": str(self.runtime_dir),
+        }
+        for name in PROBE_ENVIRONMENT_KEYS:
+            if value := os.environ.get(name):
+                environment[name] = value
+        return environment
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    state: Literal["ok", "missing", "timeout", "failed", "unavailable"]
+    stdout: str = ""
+
+
+@dataclass(frozen=True)
+class RepairResult:
+    check_id: str
+    accepted: bool
+    exit_code: int
+    message: str
+
+    def as_json(self) -> dict[str, object]:
+        return {
+            "schemaVersion": 1,
+            "checkId": self.check_id,
+            "accepted": self.accepted,
+            "exitCode": self.exit_code,
+            "message": self.message,
+        }
+
+
+CHECK_ORDER = (
+    "desktop.hyprland", "desktop.quickshell", "desktop.notifications", "desktop.portals",
+    "desktop.hyprpaper", "desktop.hypridle", "desktop.vicinae", "input.pipewire",
+    "input.clipboard", "input.wallpaper", "input.capture", "input.ocr", "input.brightness",
+    "integration.nextcloud", "integration.rustdesk", "integration.kdeconnect", "integration.bluebubbles",
+    "integration.home-assistant", "integration.calendar", "panama.runtime-links", "panama.vicinae-commands",
+    "panama.selected-terminal", "panama.selected-launcher", "panama.processes", "panama.caffeine",
+)
+
+SYSTEMCTL_COMMANDS = {
+    "hyprpaper": ("systemctl", "--user", "is-active", "--quiet", "hyprpaper.service"),
+    "hypridle": ("systemctl", "--user", "is-active", "--quiet", "hypridle.service"),
+    "vicinae": ("systemctl", "--user", "is-active", "--quiet", "vicinae.service"),
+    "pipewire": ("systemctl", "--user", "is-active", "--quiet", "pipewire.service"),
+    "nextcloud": ("systemctl", "--user", "is-active", "--quiet", "nextcloud.service"),
+    "rustdesk": ("systemctl", "--user", "is-active", "--quiet", "rustdesk.service"),
+}
+REPAIR_COMMANDS = MappingProxyType({
+    "desktop.hyprpaper": ("systemctl", "--user", "restart", "hyprpaper.service"),
+    "desktop.hypridle": ("systemctl", "--user", "restart", "hypridle.service"),
+    "desktop.vicinae": ("systemctl", "--user", "restart", "vicinae.service"),
+    "desktop.quickshell": ("panama-action", "restart-shell"),
+})
+RUNTIME_LINK_TARGETS = (
+    ("hypr", Path("config/dot/hypr")),
+    ("quickshell", Path("config/dot/quickshell")),
+    ("uwsm", Path("config/dot/uwsm")),
+    ("vicinae", Path("config/dot/vicinae")),
+)
+REPAIR_IDS = frozenset((*REPAIR_COMMANDS.keys(), "panama.runtime-links", "panama.vicinae-commands", "panama.caffeine"))
+PROCESS_NAMES = ("quickshell", "vicinae", "hyprpaper", "hypridle")
+VERSION_PATTERN = re.compile(r"\b\d+(?:\.\d+){0,3}(?:[-+._][A-Za-z0-9._-]+)?\b")
+REVISION_PATTERN = re.compile(r"\b[0-9a-f]{7,40}\b", re.IGNORECASE)
+PROBE_ENVIRONMENT_KEYS = (
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TZ",
+    "DBUS_SESSION_BUS_ADDRESS",
+    "WAYLAND_DISPLAY",
+    "DISPLAY",
+    "XAUTHORITY",
+    "PANAMA_DOCTOR_FIXTURE_STOPPED",
+    "PANAMA_DOCTOR_FIXTURE_PROCESSES",
+    "PANAMA_DOCTOR_FIXTURE_BUS",
+    "PANAMA_DOCTOR_FIXTURE_QS",
+    "PANAMA_DOCTOR_FIXTURE_QS_VERSION",
+    "PANAMA_DOCTOR_FIXTURE_BLUEBUBBLES",
+    "PANAMA_DOCTOR_FIXTURE_CALENDAR",
+    "PANAMA_DOCTOR_FIXTURE_BRIGHTNESS",
+    "PANAMA_DOCTOR_FIXTURE_CAFFEINE",
+)
+CHECK_TITLES = {
+    "desktop.hyprland": "Hyprland",
+    "desktop.quickshell": "Quickshell",
+    "desktop.notifications": "Notifications",
+    "desktop.portals": "Desktop portals",
+    "desktop.hyprpaper": "Hyprpaper",
+    "desktop.hypridle": "Hypridle",
+    "desktop.vicinae": "Vicinae",
+    "input.pipewire": "PipeWire",
+    "input.clipboard": "Clipboard",
+    "input.wallpaper": "Wallpaper",
+    "input.capture": "Capture",
+    "input.ocr": "OCR",
+    "input.brightness": "External monitor brightness",
+    "integration.nextcloud": "Nextcloud",
+    "integration.rustdesk": "RustDesk",
+    "integration.kdeconnect": "KDE Connect",
+    "integration.bluebubbles": "BlueBubbles",
+    "integration.home-assistant": "Home Assistant",
+    "integration.calendar": "Calendar",
+    "panama.runtime-links": "Panama runtime links",
+    "panama.vicinae-commands": "Panama commands",
+    "panama.selected-terminal": "Selected terminal",
+    "panama.selected-launcher": "Selected launcher",
+    "panama.processes": "Panama processes",
+    "panama.caffeine": "Caffeine inhibitor",
+}
+
+
+def environment_path(name: str, default: Path) -> Path:
+    value = os.environ.get(name)
+    return Path(value).expanduser() if value else default
+
+
+def config_from_environment() -> DoctorConfig:
+    home = environment_path("PANAMA_DOCTOR_HOME", Path.home())
+    config_home = environment_path("PANAMA_DOCTOR_CONFIG_HOME", Path(os.environ.get("XDG_CONFIG_HOME", home / ".config")))
+    state_home = environment_path("PANAMA_DOCTOR_STATE_HOME", Path(os.environ.get("XDG_STATE_HOME", home / ".local/state")))
+    runtime_dir = environment_path("PANAMA_DOCTOR_RUNTIME_DIR", Path(os.environ.get("XDG_RUNTIME_DIR", "/run/user/0")))
+    root = environment_path("PANAMA_DOCTOR_ROOT", Path(__file__).resolve().parents[4])
+    try:
+        timeout = float(os.environ.get("PANAMA_DOCTOR_TIMEOUT", "3"))
+    except ValueError:
+        timeout = 3.0
+    return DoctorConfig(root, home, config_home, state_home, runtime_dir, os.environ.get("PANAMA_DOCTOR_PATH", os.environ.get("PATH", "")), max(0.05, min(timeout, 15.0)))
+
+
+def run_command(command: tuple[str, ...], config: DoctorConfig, cwd: Path | None = None) -> CommandResult:
+    """Run an authored read-only command without reporting its unparsed output."""
+    try:
+        completed = subprocess.run(command, capture_output=True, text=True, timeout=config.timeout, check=False, env=config.command_env, cwd=cwd)
+    except FileNotFoundError:
+        return CommandResult("missing")
+    except subprocess.TimeoutExpired:
+        return CommandResult("timeout")
+    except OSError:
+        return CommandResult("unavailable")
+    if completed.returncode != 0:
+        return CommandResult("failed")
+    return CommandResult("ok", completed.stdout)
+
+
+def run_repair_command(command: tuple[str, ...], config: DoctorConfig, cwd: Path | None = None) -> tuple[int, str]:
+    """Execute one authored repair argv and retain output only for strict parsing."""
+    try:
+        completed = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            timeout=config.timeout,
+            check=False,
+            env=config.command_env,
+            cwd=cwd,
+        )
+    except FileNotFoundError:
+        return 127, ""
+    except subprocess.TimeoutExpired:
+        return 124, ""
+    except OSError:
+        return 126, ""
+    exit_code = completed.returncode if 0 <= completed.returncode <= 255 else 1
+    return exit_code, completed.stdout
+
+
+def executable_exists(name: str, config: DoctorConfig) -> bool:
+    return shutil.which(name, path=config.path) is not None
+
+
+def action_json(action: Action) -> dict[str, object]:
+    result: dict[str, object] = {"kind": action.kind, "label": action.label, "confirm": action.confirm}
+    if action.target is not None:
+        result["target"] = action.target
+    return result
+
+
+def check_json(check: Check) -> dict[str, object]:
+    result: dict[str, object] = {"id": check.id, "group": check.group, "title": check.title, "status": check.status, "detail": check.detail}
+    if check.action is not None:
+        result["action"] = action_json(check.action)
+    return result
+
+
+def group_for(check_id: str) -> Group:
+    if check_id.startswith("desktop."):
+        return "desktop-foundation"
+    if check_id.startswith("input."):
+        return "input-media"
+    if check_id.startswith("integration."):
+        return "integrations"
+    return "panama-tools"
+
+
+def service_check(check_id: str, title: str, service: str, config: DoctorConfig, action: Action | None = None) -> Check:
+    result = run_command(SYSTEMCTL_COMMANDS[service], config)
+    if result.state == "ok":
+        return Check(check_id, group_for(check_id), title, "ok", "Service is active.")
+    if result.state in {"missing", "unavailable"}:
+        return Check(check_id, group_for(check_id), title, "error", "Required system service probe is unavailable.")
+    return Check(check_id, group_for(check_id), title, "warning", "Service is not active.", action)
+
+
+def ipc_target(config: DoctorConfig, target: str) -> CommandResult:
+    result = run_command(("qs", "ipc", "show"), config)
+    if result.state != "ok":
+        return result
+    return CommandResult("ok") if f"target {target}" in result.stdout.splitlines() else CommandResult("failed")
+
+
+def simple_ipc_check(check_id: str, title: str, target: str, config: DoctorConfig) -> Check:
+    result = ipc_target(config, target)
+    if result.state == "ok":
+        return Check(check_id, "input-media", title, "ok", "Panama IPC target is available.")
+    if result.state == "missing":
+        return Check(check_id, "input-media", title, "error", "Required Quickshell executable is unavailable.")
+    if result.state == "timeout":
+        return Check(check_id, "input-media", title, "warning", "Panama IPC probe timed out.")
+    return Check(check_id, "input-media", title, "warning", "Panama IPC target is unavailable.")
+
+
+def check_hyprland(config: DoctorConfig) -> Check:
+    if "hyprland" in os.environ.get("XDG_CURRENT_DESKTOP", "").casefold():
+        return Check("desktop.hyprland", "desktop-foundation", "Hyprland", "ok", "Hyprland session detected.")
+    return Check("desktop.hyprland", "desktop-foundation", "Hyprland", "error", "Hyprland session is not active.")
+
+
+def check_quickshell(config: DoctorConfig) -> Check:
+    result = run_command(("qs", "--version"), config)
+    repair = Action("repair", "Restart Panama", True)
+    if result.state == "ok" and VERSION_PATTERN.search(result.stdout):
+        return Check("desktop.quickshell", "desktop-foundation", "Quickshell", "ok", "Quickshell executable is available.")
+    if result.state == "missing":
+        return Check("desktop.quickshell", "desktop-foundation", "Quickshell", "error", "Required Quickshell executable is unavailable.", repair)
+    return Check("desktop.quickshell", "desktop-foundation", "Quickshell", "warning", "Quickshell probe returned an invalid result.", repair)
+
+
+def check_notifications(config: DoctorConfig) -> Check:
+    result = ipc_target(config, "notifications")
+    return Check("desktop.notifications", "desktop-foundation", "Notifications", "ok", "Notification service is available.") if result.state == "ok" else Check("desktop.notifications", "desktop-foundation", "Notifications", "warning", "Notification service is unavailable.")
+
+
+def check_portals(config: DoctorConfig) -> Check:
+    result = run_command(("busctl", "--user", "--no-pager", "list"), config)
+    if result.state == "ok" and any(line.startswith("org.freedesktop.portal.Desktop ") for line in result.stdout.splitlines()):
+        return Check("desktop.portals", "desktop-foundation", "Desktop portals", "ok", "Desktop portal service is available.")
+    detail = "Desktop portal probe timed out." if result.state == "timeout" else "Desktop portal probe is unavailable." if result.state == "missing" else "Desktop portal service is unavailable."
+    return Check("desktop.portals", "desktop-foundation", "Desktop portals", "warning", detail)
+
+
+def check_brightness(config: DoctorConfig) -> Check:
+    result = run_command(("panama-brightness", "list"), config)
+    instructions = Action("instructions", "View setup instructions", target="ddc-permissions")
+    if result.state == "timeout":
+        return Check("input.brightness", "input-media", "External monitor brightness", "warning", "DDC/CI probe timed out.", instructions)
+    if result.state != "ok":
+        return Check("input.brightness", "input-media", "External monitor brightness", "warning", "DDC/CI support is unavailable.", instructions)
+    try:
+        listing = json.loads(result.stdout)
+        displays, error = listing["displays"], listing["error"]
+        if not isinstance(displays, list) or not isinstance(error, str):
+            raise ValueError
+    except (json.JSONDecodeError, KeyError, TypeError, ValueError):
+        return Check("input.brightness", "input-media", "External monitor brightness", "warning", "DDC/CI probe returned an invalid result.", instructions)
+    if error:
+        return Check("input.brightness", "input-media", "External monitor brightness", "warning", "No accessible DDC/CI bus.", instructions)
+    if not displays:
+        return Check("input.brightness", "input-media", "External monitor brightness", "unconfigured", "No DDC/CI display is configured.")
+    return Check("input.brightness", "input-media", "External monitor brightness", "ok", f"{len(displays)} DDC/CI display{'s' if len(displays) != 1 else ''} available.")
+
+
+def check_nextcloud(config: DoctorConfig) -> Check:
+    if not (config.config_home / "autostart" / "nextcloud.desktop").is_file():
+        return Check("integration.nextcloud", "integrations", "Nextcloud", "unconfigured", "Nextcloud autostart is not configured.")
+    return service_check("integration.nextcloud", "Nextcloud", "nextcloud", config, Action("open", "Open Nextcloud"))
+
+
+def check_rustdesk(config: DoctorConfig) -> Check:
+    if not executable_exists("rustdesk", config):
+        return Check("integration.rustdesk", "integrations", "RustDesk", "unconfigured", "RustDesk is not installed.")
+    return service_check("integration.rustdesk", "RustDesk", "rustdesk", config, Action("open", "Open RustDesk"))
+
+
+def check_kdeconnect(config: DoctorConfig) -> Check:
+    if not executable_exists("kdeconnect-cli", config):
+        return Check("integration.kdeconnect", "integrations", "KDE Connect", "unconfigured", "KDE Connect is not installed.")
+    result = run_command(("busctl", "--user", "--no-pager", "list"), config)
+    if result.state == "ok" and any(line.startswith("org.kde.kdeconnect ") for line in result.stdout.splitlines()):
+        return Check("integration.kdeconnect", "integrations", "KDE Connect", "ok", "KDE Connect service is available.")
+    return Check("integration.kdeconnect", "integrations", "KDE Connect", "warning", "KDE Connect service is unavailable.", Action("open", "Open KDE Connect"))
+
+
+def check_bluebubbles(config: DoctorConfig) -> Check:
+    result = run_command(("flatpak", "info", "app.bluebubbles.BlueBubbles"), config)
+    if result.state == "ok":
+        return Check("integration.bluebubbles", "integrations", "BlueBubbles", "ok", "BlueBubbles is installed.")
+    if result.state in {"missing", "failed"}:
+        return Check("integration.bluebubbles", "integrations", "BlueBubbles", "unconfigured", "BlueBubbles is not installed.")
+    return Check("integration.bluebubbles", "integrations", "BlueBubbles", "warning", "BlueBubbles installation probe timed out.", Action("open", "Open BlueBubbles"))
+
+
+def check_home_assistant(config: DoctorConfig) -> Check:
+    configured = all(name in os.environ for name in ("PANAMA_HOME_ASSISTANT_URL", "PANAMA_HOME_ASSISTANT_TOKEN"))
+    helper = config.config_home / "quickshell" / "scripts" / "panama-home-assistant"
+    if not configured:
+        return Check("integration.home-assistant", "integrations", "Home Assistant", "unconfigured", "Home Assistant is not configured.")
+    if not helper.is_file():
+        return Check("integration.home-assistant", "integrations", "Home Assistant", "warning", "Home Assistant bridge is unavailable.", Action("open", "Open Home settings", target="home-phone"))
+    return Check("integration.home-assistant", "integrations", "Home Assistant", "ok", "Home Assistant credentials are configured.")
+
+
+def check_calendar(config: DoctorConfig) -> Check:
+    result = run_command(("calendar-agenda", "probe"), config)
+    action = Action("open", "Open Date & Time", target="datetime")
+    if result.state == "missing":
+        return Check("integration.calendar", "integrations", "Calendar", "unconfigured", "Calendar integration is not installed.")
+    if result.state == "timeout":
+        return Check("integration.calendar", "integrations", "Calendar", "warning", "Calendar probe timed out.", action)
+    if result.state != "ok":
+        return Check("integration.calendar", "integrations", "Calendar", "warning", "Calendar probe failed.", action)
+    try:
+        enabled_sources = json.loads(result.stdout)["enabledSources"]
+        if not isinstance(enabled_sources, int) or isinstance(enabled_sources, bool):
+            raise ValueError
+    except (json.JSONDecodeError, KeyError, TypeError, ValueError):
+        return Check("integration.calendar", "integrations", "Calendar", "warning", "Calendar probe returned an invalid result.", action)
+    if enabled_sources <= 0:
+        return Check("integration.calendar", "integrations", "Calendar", "unconfigured", "No enabled calendar source is configured.")
+    return Check("integration.calendar", "integrations", "Calendar", "ok", f"{enabled_sources} enabled calendar source{'s' if enabled_sources != 1 else ''} configured.")
+
+
+def check_runtime_links(config: DoctorConfig) -> Check:
+    def valid_link(name: str, relative_source: Path) -> bool:
+        destination = config.config_home / name
+        source = config.root / relative_source
+        try:
+            return source.is_dir() and destination.is_symlink() \
+                and destination.resolve(strict=False) == source.resolve(strict=True)
+        except OSError:
+            return False
+
+    if any(not valid_link(name, relative_source) for name, relative_source in RUNTIME_LINK_TARGETS):
+        return Check("panama.runtime-links", "panama-tools", "Panama runtime links", "warning", "One or more Panama runtime links are unavailable.", Action("repair", "Repair runtime links"))
+    return Check("panama.runtime-links", "panama-tools", "Panama runtime links", "ok", "Panama runtime links are available.")
+
+
+def check_vicinae_commands(config: DoctorConfig) -> Check:
+    source = config.root / "config/local/share/vicinae/scripts"
+    installed = config.home / ".local/share/vicinae/scripts/panama"
+    try:
+        linked = source.is_dir() and installed.is_symlink() \
+            and installed.resolve(strict=False) == source.resolve(strict=True)
+    except OSError:
+        linked = False
+    if linked:
+        return Check("panama.vicinae-commands", "panama-tools", "Panama commands", "ok", "Panama Vicinae commands are linked.")
+    return Check("panama.vicinae-commands", "panama-tools", "Panama commands", "warning", "Panama Vicinae commands are not linked.", Action("repair", "Repair command link"))
+
+
+def executable_check(check_id: str, title: str, executable: str, config: DoctorConfig) -> Check:
+    if executable_exists(executable, config):
+        return Check(check_id, group_for(check_id), title, "ok", f"{title} executable is available.")
+    return Check(check_id, group_for(check_id), title, "warning", f"{title} executable is unavailable.")
+
+
+def check_processes(config: DoctorConfig) -> Check:
+    counts: list[int] = []
+    for name in PROCESS_NAMES:
+        result = run_command(("pgrep", "-u", str(os.getuid()), "-x", name), config)
+        if result.state == "ok":
+            pids = result.stdout.splitlines()
+            if not pids or any(not pid.isdecimal() for pid in pids):
+                return Check("panama.processes", "panama-tools", "Panama processes", "warning", "Process probe returned an invalid result.")
+            counts.append(len(pids))
+        elif result.state == "failed":
+            counts.append(0)
+        else:
+            return Check("panama.processes", "panama-tools", "Panama processes", "warning", "Process probe is unavailable.")
+    if any(count > 1 for count in counts):
+        return Check("panama.processes", "panama-tools", "Panama processes", "warning", "Duplicate Panama desktop processes detected.")
+    if counts[0] == 0:
+        return Check("panama.processes", "panama-tools", "Panama processes", "error", "Quickshell process is not running.")
+    return Check("panama.processes", "panama-tools", "Panama processes", "ok", "Panama desktop process counts are normal.")
+
+
+def check_caffeine(config: DoctorConfig) -> Check:
+    result = run_command(("systemd-inhibit", "--list", "--no-pager", "--no-legend"), config)
+    if result.state != "ok":
+        return Check("panama.caffeine", "panama-tools", "Caffeine inhibitor", "warning", "Caffeine inhibitor probe is unavailable.")
+    inhibitor_rows = parse_caffeine_rows(result.stdout, str(os.getuid()))
+    if inhibitor_rows is None:
+        return Check("panama.caffeine", "panama-tools", "Caffeine inhibitor", "warning", "Caffeine inhibitor probe returned an invalid result.")
+    inhibitors = len(dict.fromkeys(int(row[3]) for row in inhibitor_rows))
+    if inhibitors > 1:
+        return Check("panama.caffeine", "panama-tools", "Caffeine inhibitor", "warning", "Duplicate Panama Caffeine inhibitors detected.", Action("repair", "Release duplicate inhibitors"))
+    if inhibitors == 1:
+        return Check("panama.caffeine", "panama-tools", "Caffeine inhibitor", "ok", "One Panama Caffeine inhibitor is active.")
+    return Check("panama.caffeine", "panama-tools", "Caffeine inhibitor", "ok", "No Panama Caffeine inhibitor is active.")
+
+
+def parse_version(result: CommandResult, pattern: re.Pattern[str] = VERSION_PATTERN) -> str:
+    match = pattern.search(result.stdout) if result.state == "ok" else None
+    return match.group(0) if match else "unavailable"
+
+
+def context_versions(config: DoctorConfig) -> list[dict[str, str]]:
+    hyprland = run_command(("hyprctl", "version"), config)
+    quickshell = run_command(("qs", "--version"), config)
+    revision = run_command(("git", "rev-parse", "--short", "HEAD"), config, config.root)
+    fedora = "unavailable"
+    try:
+        match = re.search(r"^VERSION_ID=\"?([^\n\"]+)", Path("/etc/os-release").read_text(encoding="utf-8"), re.MULTILINE)
+        if match and re.fullmatch(r"[0-9.]+", match.group(1)):
+            fedora = match.group(1)
+    except OSError:
+        pass
+    return [{"id": "hyprland", "version": parse_version(hyprland)}, {"id": "quickshell", "version": parse_version(quickshell)}, {"id": "fedora", "version": fedora}, {"id": "panama", "version": parse_version(revision, REVISION_PATTERN)}]
+
+
+def unavailable_check(check_id: str) -> Check:
+    return Check(check_id, group_for(check_id), CHECK_TITLES[check_id], "warning", "Diagnostic probe could not be completed.")
+
+
+def unavailable_versions() -> list[dict[str, str]]:
+    return [{"id": name, "version": "unavailable"} for name in ("hyprland", "quickshell", "fedora", "panama")]
+
+
+def collect_checks(config: DoctorConfig) -> list[Check]:
+    probes: dict[str, Callable[[], Check]] = {
+        "desktop.hyprland": lambda: check_hyprland(config), "desktop.quickshell": lambda: check_quickshell(config), "desktop.notifications": lambda: check_notifications(config), "desktop.portals": lambda: check_portals(config),
+        "desktop.hyprpaper": lambda: service_check("desktop.hyprpaper", "Hyprpaper", "hyprpaper", config, Action("repair", "Restart Hyprpaper")), "desktop.hypridle": lambda: service_check("desktop.hypridle", "Hypridle", "hypridle", config, Action("repair", "Restart Hypridle")), "desktop.vicinae": lambda: service_check("desktop.vicinae", "Vicinae", "vicinae", config, Action("repair", "Restart Vicinae")), "input.pipewire": lambda: service_check("input.pipewire", "PipeWire", "pipewire", config),
+        "input.clipboard": lambda: simple_ipc_check("input.clipboard", "Clipboard", "clipboard", config), "input.wallpaper": lambda: simple_ipc_check("input.wallpaper", "Wallpaper", "wallpaper", config), "input.capture": lambda: simple_ipc_check("input.capture", "Capture", "capture", config), "input.ocr": lambda: executable_check("input.ocr", "OCR", "tesseract", config), "input.brightness": lambda: check_brightness(config),
+        "integration.nextcloud": lambda: check_nextcloud(config), "integration.rustdesk": lambda: check_rustdesk(config), "integration.kdeconnect": lambda: check_kdeconnect(config), "integration.bluebubbles": lambda: check_bluebubbles(config), "integration.home-assistant": lambda: check_home_assistant(config), "integration.calendar": lambda: check_calendar(config),
+        "panama.runtime-links": lambda: check_runtime_links(config), "panama.vicinae-commands": lambda: check_vicinae_commands(config), "panama.selected-terminal": lambda: executable_check("panama.selected-terminal", "Selected terminal", "kitty", config), "panama.selected-launcher": lambda: executable_check("panama.selected-launcher", "Selected launcher", "vicinae", config), "panama.processes": lambda: check_processes(config), "panama.caffeine": lambda: check_caffeine(config),
+    }
+    with ThreadPoolExecutor(max_workers=8) as executor:
+        futures = {check_id: executor.submit(probes[check_id]) for check_id in CHECK_ORDER}
+        checks: list[Check] = []
+        for check_id in CHECK_ORDER:
+            try:
+                checks.append(futures[check_id].result())
+            except Exception:
+                checks.append(unavailable_check(check_id))
+        return checks
+
+
+def snapshot(config: DoctorConfig) -> dict[str, object]:
+    try:
+        checks = collect_checks(config)
+    except Exception:
+        checks = [unavailable_check(check_id) for check_id in CHECK_ORDER]
+    counts = {status: sum(check.status == status for check in checks) for status in ("ok", "warning", "error", "unconfigured")}
+    overall: Literal["healthy", "warning", "error"] = "error" if counts["error"] else "warning" if counts["warning"] else "healthy"
+    session = "hyprland" if "hyprland" in os.environ.get("XDG_CURRENT_DESKTOP", "").casefold() else "other"
+    try:
+        versions = context_versions(config)
+    except Exception:
+        versions = unavailable_versions()
+    return {"schemaVersion": 1, "generatedAt": datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z"), "summary": {"status": overall, "healthy": counts["ok"], "warnings": counts["warning"], "errors": counts["error"], "unconfigured": counts["unconfigured"]}, "context": {"session": session, "versions": versions}, "checks": [check_json(check) for check in checks]}
+
+
+def repair_authored_command(check_id: str, config: DoctorConfig) -> RepairResult:
+    command = REPAIR_COMMANDS[check_id]
+    exit_code, _ = run_repair_command(command, config)
+    message = "Repair completed. A fresh health check will verify recovery." if exit_code == 0 \
+        else "The authored repair command could not be completed."
+    return RepairResult(check_id, True, exit_code, message)
+
+
+def lexical_path(path: Path) -> Path:
+    """Normalize dot segments without following any filesystem symlink."""
+    return Path(os.path.abspath(os.fspath(path)))
+
+
+def lexical_link_target(destination: Path) -> Path:
+    target = Path(os.readlink(destination))
+    return lexical_path(target if target.is_absolute() else destination.parent / target)
+
+
+def renameat2(source: Path, destination: Path, flags: int) -> None:
+    """Call Linux renameat2 with fixed flags selected by authored code."""
+    libc = ctypes.CDLL(None, use_errno=True)
+    function = getattr(libc, "renameat2", None)
+    if function is None:
+        raise OSError(errno.ENOSYS, "renameat2 is unavailable")
+    function.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]
+    function.restype = ctypes.c_int
+    result = function(
+        AT_FDCWD,
+        os.fsencode(source),
+        AT_FDCWD,
+        os.fsencode(destination),
+        flags,
+    )
+    if result != 0:
+        error = ctypes.get_errno()
+        raise OSError(error, os.strerror(error), destination)
+
+
+def rename_exchange(source: Path, destination: Path) -> None:
+    renameat2(source, destination, RENAME_EXCHANGE)
+
+
+def rename_noreplace(source: Path, destination: Path) -> None:
+    renameat2(source, destination, RENAME_NOREPLACE)
+
+
+def create_symlink_candidate(destination: Path, source: Path) -> Path:
+    """Create one unpredictable authored sibling candidate symlink."""
+    for _ in range(32):
+        candidate = destination.with_name(
+            f".panama-link-{destination.name}-{os.getpid()}-{secrets.token_hex(8)}"
+        )
+        try:
+            os.symlink(source, candidate, target_is_directory=True)
+            return candidate
+        except FileExistsError:
+            continue
+    raise OSError("Could not allocate an authored temporary link")
+
+
+def cleanup_candidate(candidate: Path) -> None:
+    try:
+        candidate.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def install_absent_symlink(destination: Path, source: Path) -> Literal["repaired", "blocked", "failed"]:
+    candidate = create_symlink_candidate(destination, source)
+    try:
+        try:
+            rename_noreplace(candidate, destination)
+        except FileExistsError:
+            return "blocked"
+        except OSError:
+            return "failed"
+        return "repaired"
+    finally:
+        cleanup_candidate(candidate)
+
+
+def exchange_owned_symlink(
+    destination: Path,
+    source: Path,
+    authored_sources: frozenset[Path],
+) -> Literal["repaired", "blocked", "failed"]:
+    """Exchange first, then validate the exact object removed from destination."""
+    candidate = create_symlink_candidate(destination, source)
+    exchanged = False
+    rolled_back = False
+    try:
+        try:
+            rename_exchange(candidate, destination)
+            exchanged = True
+        except OSError:
+            return "failed"
+
+        try:
+            old_is_authored = candidate.is_symlink() \
+                and lexical_link_target(candidate) in authored_sources
+        except OSError:
+            old_is_authored = False
+        if old_is_authored:
+            cleanup_candidate(candidate)
+            return "repaired"
+
+        try:
+            rename_exchange(candidate, destination)
+            rolled_back = True
+        except OSError:
+            # The displaced object remains at the unpredictable candidate path;
+            # never unlink it when rollback could not restore ownership.
+            return "failed"
+
+        try:
+            restored_candidate_is_ours = candidate.is_symlink() \
+                and lexical_link_target(candidate) == source
+        except OSError:
+            restored_candidate_is_ours = False
+        if not restored_candidate_is_ours:
+            return "failed"
+        cleanup_candidate(candidate)
+        return "blocked"
+    finally:
+        if not exchanged or rolled_back:
+            try:
+                if candidate.is_symlink() and lexical_link_target(candidate) == source:
+                    cleanup_candidate(candidate)
+            except OSError:
+                pass
+
+
+def repair_runtime_links(config: DoctorConfig) -> RepairResult:
+    root = lexical_path(config.root)
+    sources = [(name, lexical_path(config.root / relative_source)) for name, relative_source in RUNTIME_LINK_TARGETS]
+    if any(not source.is_dir() for _, source in sources):
+        return RepairResult("panama.runtime-links", True, 1, "Tracked Panama link destinations are unavailable.")
+    if any(not source.is_relative_to(root) for _, source in sources):
+        return RepairResult("panama.runtime-links", True, 1, "Tracked Panama link destinations are invalid.")
+    authored_sources = frozenset(source for _, source in sources)
+
+    try:
+        config.config_home.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return RepairResult("panama.runtime-links", True, 1, "Panama runtime links could not be accessed.")
+
+    blocked = False
+    failed = False
+    for name, source in sources:
+        destination = config.config_home / name
+        try:
+            if destination.is_symlink():
+                current_target = lexical_link_target(destination)
+                if current_target == source:
+                    continue
+                if current_target not in authored_sources:
+                    blocked = True
+                    continue
+                outcome = exchange_owned_symlink(destination, source, authored_sources)
+                blocked = blocked or outcome == "blocked"
+                failed = failed or outcome == "failed"
+            elif destination.exists():
+                # A regular file or directory is user-owned unless proven
+                # otherwise. Report it, but never replace it.
+                blocked = True
+            else:
+                outcome = install_absent_symlink(destination, source)
+                blocked = blocked or outcome == "blocked"
+                failed = failed or outcome == "failed"
+        except OSError:
+            failed = True
+
+    if failed:
+        return RepairResult("panama.runtime-links", True, 1, "One or more Panama runtime links could not be recreated.")
+    if blocked:
+        return RepairResult("panama.runtime-links", True, 1, "A user-owned runtime path is blocking a Panama link.")
+    return RepairResult("panama.runtime-links", True, 0, "Panama runtime links were recreated. A fresh health check will verify them.")
+
+
+def repair_vicinae_commands(config: DoctorConfig) -> RepairResult:
+    helper = config.root / "setup/scripts/link-vicinae-scripts"
+    if not helper.is_file():
+        return RepairResult("panama.vicinae-commands", True, 127, "The authored Vicinae link helper is unavailable.")
+    exit_code, _ = run_repair_command((str(helper),), config, config.root)
+    message = "Panama commands were relinked. A fresh health check will verify them." if exit_code == 0 \
+        else "Panama commands could not be relinked."
+    return RepairResult("panama.vicinae-commands", True, exit_code, message)
+
+
+def parse_caffeine_rows(output: str, uid: str) -> list[InhibitorRow] | None:
+    inhibitor_rows: list[InhibitorRow] = []
+    for line in output.splitlines():
+        parts = line.split()
+        if len(parts) < 2 or parts[0] != "Panama" or parts[1] != uid:
+            continue
+        if len(parts) != 8:
+            if "Caffeine" in parts:
+                return None
+            continue
+        if parts[6] != "Caffeine" or parts[7] != "block":
+            continue
+        if not parts[3].isdecimal():
+            return None
+        inhibitor_rows.append(tuple(parts))
+    return inhibitor_rows
+
+
+def close_pidfds(pidfds: list[int]) -> None:
+    for pidfd in pidfds:
+        try:
+            os.close(pidfd)
+        except OSError:
+            pass
+
+
+def signal_caffeine_pidfds(
+    pidfds: list[int],
+    sender: Callable[..., None] | None = None,
+) -> Literal["released", "preflight-failed", "incomplete"]:
+    send = sender or signal.pidfd_send_signal
+    for pidfd in pidfds:
+        try:
+            send(pidfd, 0, None, 0)
+        except (OSError, ValueError):
+            return "preflight-failed"
+
+    incomplete = False
+    for pidfd in pidfds:
+        try:
+            send(pidfd, signal.SIGTERM, None, 0)
+        except ProcessLookupError:
+            continue
+        except OSError as error:
+            if error.errno != errno.ESRCH:
+                incomplete = True
+        except ValueError:
+            incomplete = True
+    return "incomplete" if incomplete else "released"
+
+
+def repair_caffeine(config: DoctorConfig) -> RepairResult:
+    list_command = ("systemd-inhibit", "--list", "--no-pager", "--no-legend")
+    list_exit, output = run_repair_command(list_command, config)
+    if list_exit != 0:
+        return RepairResult("panama.caffeine", True, list_exit, "Caffeine inhibitors could not be inspected.")
+
+    uid = str(os.getuid())
+    inhibitor_rows = parse_caffeine_rows(output, uid)
+    if inhibitor_rows is None:
+        return RepairResult("panama.caffeine", True, 1, "Caffeine inhibitor metadata was invalid; nothing was released.")
+    inhibitor_pids = list(dict.fromkeys(int(row[3]) for row in inhibitor_rows))
+
+    if len(inhibitor_pids) <= 1:
+        return RepairResult("panama.caffeine", True, 0, "No duplicate Panama Caffeine inhibitors needed release.")
+
+    duplicates = inhibitor_pids[1:]
+    if not hasattr(os, "pidfd_open") or not hasattr(signal, "pidfd_send_signal"):
+        return RepairResult("panama.caffeine", True, 1, "Safe Caffeine inhibitor release is unavailable on this system.")
+
+    pidfds: list[int] = []
+    try:
+        try:
+            pidfds = [os.pidfd_open(pid, 0) for pid in duplicates]
+        except (OSError, ValueError):
+            return RepairResult("panama.caffeine", True, 1, "A duplicate inhibitor changed before it could be safely released.")
+
+        second_exit, second_output = run_repair_command(list_command, config)
+        if second_exit != 0:
+            return RepairResult("panama.caffeine", True, second_exit, "Caffeine inhibitors could not be revalidated; nothing was released.")
+        second_rows = parse_caffeine_rows(second_output, uid)
+        if second_rows is None or second_rows != inhibitor_rows:
+            return RepairResult("panama.caffeine", True, 1, "Caffeine inhibitor metadata changed; nothing was released.")
+
+        signal_outcome = signal_caffeine_pidfds(pidfds)
+        if signal_outcome == "preflight-failed":
+            return RepairResult("panama.caffeine", True, 1, "A duplicate inhibitor changed before it could be safely released.")
+        if signal_outcome == "incomplete":
+            return RepairResult("panama.caffeine", True, 1, "One or more duplicate inhibitors could not be released.")
+    finally:
+        close_pidfds(pidfds)
+    return RepairResult("panama.caffeine", True, 0, "Duplicate Panama Caffeine inhibitors were released. A fresh health check will verify recovery.")
+
+
+def repair(check_id: str, config: DoctorConfig) -> RepairResult:
+    if check_id in REPAIR_COMMANDS:
+        return repair_authored_command(check_id, config)
+    if check_id == "panama.runtime-links":
+        return repair_runtime_links(config)
+    if check_id == "panama.vicinae-commands":
+        return repair_vicinae_commands(config)
+    if check_id == "panama.caffeine":
+        return repair_caffeine(config)
+    return RepairResult(check_id, False, 2, "This health check has no authored repair.")
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="Panama system diagnostics and bounded repairs")
+    output = parser.add_mutually_exclusive_group()
+    output.add_argument("--json", action="store_true")
+    output.add_argument("--summary", action="store_true")
+    parser.add_argument("--repair", metavar="CHECK_ID")
+    args = parser.parse_args(argv)
+
+    if args.repair is not None:
+        if args.repair not in REPAIR_IDS or args.summary:
+            result = RepairResult(args.repair, False, 2, "This health check has no authored repair.")
+        else:
+            try:
+                result = repair(args.repair, config_from_environment())
+            except Exception:
+                result = RepairResult(args.repair, True, 1, "The authored repair could not be completed.")
+        print(json.dumps(result.as_json(), separators=(",", ":"), sort_keys=False))
+        return result.exit_code
+
+    result = snapshot(config_from_environment())
+    if args.summary:
+        summary = result["summary"]
+        assert isinstance(summary, dict)
+        print(f"Panama system health: {summary['status']} ({summary['healthy']} ok, {summary['warnings']} warnings, {summary['errors']} errors, {summary['unconfigured']} unconfigured)")
+    else:
+        print(json.dumps(result, separators=(",", ":"), sort_keys=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

config/dot/quickshell/scripts/panama-kdeconnect

@@ -25,6 +25,9 @@ PLUGIN_ACTIONS = {
     "kdeconnect_share": "share",
 }
 DEVICE_OBJECT_PREFIX = "/modules/kdeconnect/devices"
+DEVICE_OBJECT_LINE = re.compile(
+    rf"(?P<path>{re.escape(DEVICE_OBJECT_PREFIX)}/(?P<id>[A-Fa-f0-9]{{32,64}}))$"
+)
 Runner = Callable[..., subprocess.CompletedProcess[str]]
 
 
@@ -107,6 +110,13 @@ def parse_string_property(output: str) -> str:
     return parts[1] if len(parts) == 2 and parts[0] == "s" else ""
 
 
+def parse_bool_property(output: str) -> bool | None:
+    parts = output.split()
+    if len(parts) != 2 or parts[0] != "b" or parts[1] not in {"true", "false"}:
+        return None
+    return parts[1] == "true"
+
+
 def run_command(
     command: list[str],
     *,
@@ -179,6 +189,82 @@ def reported_type(device_id: str, runner: Runner = subprocess.run) -> str:
     return parse_string_property(result.stdout) if result.returncode == 0 else ""
 
 
+def device_property(
+    device_id: str,
+    member: str,
+    runner: Runner = subprocess.run,
+) -> subprocess.CompletedProcess[str]:
+    return run_command(
+        [
+            "busctl",
+            "--user",
+            "get-property",
+            "org.kde.kdeconnect",
+            device_object(device_id),
+            "org.kde.kdeconnect.device",
+            member,
+        ],
+        runner=runner,
+    )
+
+
+def dbus_device_ids(runner: Runner = subprocess.run) -> list[str]:
+    try:
+        result = run_command(
+            ["busctl", "--user", "tree", "org.kde.kdeconnect"],
+            runner=runner,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return []
+    if result.returncode != 0:
+        return []
+    return [
+        match.group("id")
+        for line in result.stdout.splitlines()
+        if (match := DEVICE_OBJECT_LINE.search(line.strip())) is not None
+    ]
+
+
+def dbus_devices(runner: Runner = subprocess.run) -> list[dict[str, object]]:
+    devices: list[dict[str, object]] = []
+    for device_id in dbus_device_ids(runner):
+        try:
+            name_result = device_property(device_id, "name", runner)
+            type_result = device_property(device_id, "type", runner)
+            paired_result = device_property(device_id, "isPaired", runner)
+            reachable_result = device_property(device_id, "isReachable", runner)
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            continue
+        name = parse_string_property(name_result.stdout) if name_result.returncode == 0 else ""
+        device_type = parse_string_property(type_result.stdout) if type_result.returncode == 0 else ""
+        paired = parse_bool_property(paired_result.stdout) if paired_result.returncode == 0 else None
+        reachable = parse_bool_property(reachable_result.stdout) if reachable_result.returncode == 0 else None
+        if not name or paired is not True or reachable is None:
+            continue
+        try:
+            plugins = device_plugins(device_id, runner)
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            plugins = []
+        actions = sorted(
+            {
+                action
+                for plugin, action in PLUGIN_ACTIONS.items()
+                if plugin in plugins
+            }
+        )
+        devices.append(
+            {
+                "id": device_id,
+                "name": name,
+                "type": device_type or inferred_type(name),
+                "paired": paired,
+                "reachable": reachable,
+                "actions": actions,
+            }
+        )
+    return devices
+
+
 def collect_status(runner: Runner = subprocess.run) -> dict[str, object]:
     try:
         listing = run_command(
@@ -200,15 +286,24 @@ def collect_status(runner: Runner = subprocess.run) -> dict[str, object]:
             continue
         device_id = match.group("id")
         try:
-            device = normalize_device_line(
+            plugins = device_plugins(device_id, runner)
-                line,
+            device_type = reported_type(device_id, runner)
-                device_plugins(device_id, runner),
+        except (FileNotFoundError, subprocess.TimeoutExpired):
-                reported_type(device_id, runner),
+            plugins = []
-            )
+            device_type = ""
+        try:
+            device = normalize_device_line(line, plugins, device_type)
         except ValueError:
             continue
         devices.append(device)
 
+    known_ids = {str(device["id"]) for device in devices}
+    devices.extend(
+        device
+        for device in dbus_devices(runner)
+        if str(device["id"]) not in known_ids
+    )
+
     devices.sort(
         key=lambda device: (
             not bool(device["reachable"]),

config/dot/quickshell/scripts/panama-power-profile

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+
+# System power profile, via the PowerProfiles D-Bus API.
+#
+# GNOME's Power panel offers Balanced / Performance / Power Saver; this is the
+# same daemon behind it. On Fedora 44 the implementation is tuned-ppd rather
+# than power-profiles-daemon, but it serves the same net.hadess.PowerProfiles
+# interface, which is why this talks to the interface rather than to either
+# binary -- powerprofilesctl is not even installed here.
+#
+# Setting a profile needs no privileges: the daemon accepts a property write
+# from the active session user.
+#
+# Usage:
+#   panama-power-profile list        -> {"profiles":[...],"active":"...","degraded":"..."}
+#   panama-power-profile set <name>
+#
+# PerformanceDegraded is reported because it is the one thing that makes the
+# choice a lie: a thermally throttled laptop reports "performance" while
+# behaving otherwise, and GNOME surfaces exactly this. It is an empty string
+# when nothing is wrong.
+
+set -uo pipefail
+
+readonly BUS_NAME=net.hadess.PowerProfiles
+readonly OBJECT=/net/hadess/PowerProfiles
+
+emit_error() {
+    printf '{"profiles":[],"active":"","degraded":"","error":%s}\n' "$(jq -Rn --arg e "$1" '$e')"
+    exit 0
+}
+
+command -v busctl >/dev/null 2>&1 || emit_error 'busctl is not available'
+
+property() {
+    busctl get-property "$BUS_NAME" "$OBJECT" "$BUS_NAME" "$1" 2>/dev/null
+}
+
+cmd_list() {
+    # A machine with no power-profiles daemon is a normal state -- plenty of
+    # desktops have none -- so it is reported rather than treated as a failure.
+    busctl status "$BUS_NAME" >/dev/null 2>&1 \
+        || emit_error 'No power profile service is running. GNOME uses power-profiles-daemon; Fedora ships tuned-ppd.'
+
+    local active degraded profiles
+    active="$(property ActiveProfile | sed 's/^s //; s/"//g')"
+    degraded="$(property PerformanceDegraded | sed 's/^s //; s/"//g')"
+
+    # Profiles is an array of dicts, which busctl renders flat:
+    #   v aa{sv} 3 2 "Profile" s "power-saver" "Driver" s "tuned" 2 "Profile" ...
+    # so each profile is the string following its own "Profile" marker. Matching
+    # the marker matters: "Driver" values sit in the same stream, and on this
+    # machine the driver is called "tuned", which a looser pattern happily
+    # reports as a fourth profile that does not exist.
+    profiles="$(property Profiles \
+        | grep -oE '"Profile" s "[a-z-]+"' \
+        | sed 's/.*s "//; s/"$//' \
+        | awk '!seen[$0]++')"
+
+    [[ -n "$profiles" ]] || emit_error 'The power profile service reported no profiles.'
+
+    jq -cn \
+        --arg active "$active" \
+        --arg degraded "$degraded" \
+        --argjson profiles "$(printf '%s\n' "$profiles" | jq -Rn '[inputs | select(length > 0)]')" \
+        '{profiles: $profiles, active: $active, degraded: $degraded, error: ""}'
+}
+
+cmd_set() {
+    local profile="${1:-}"
+    # Constrained rather than passed through: this reaches a system service.
+    [[ "$profile" =~ ^[a-z-]+$ ]] || {
+        printf 'panama-power-profile: refusing a profile name with unexpected characters\n' >&2
+        return 2
+    }
+    busctl set-property "$BUS_NAME" "$OBJECT" "$BUS_NAME" ActiveProfile s "$profile" 2>&1 >/dev/null \
+        | head -2 >&2
+    return 0
+}
+
+case "${1:-list}" in
+    list) cmd_list ;;
+    set)  shift; cmd_set "${1:-}" ;;
+    *)    printf 'usage: panama-power-profile [list|set <profile>]\n' >&2; exit 2 ;;
+esac

config/dot/quickshell/scripts/panama-theme-apps

@@ -31,6 +31,54 @@ case "$scheme" in
     *) printf 'usage: panama-theme-apps [dark|light]\n' >&2; exit 2 ;;
 esac
 
+# ── tmux ─────────────────────────────────────────────────────────────────────
+# Generated like kitty's: tmux.conf sources current-theme.conf, and that file is
+# machine state rather than configuration. Running servers are re-sourced so an
+# open session changes now instead of at next launch -- tmux applies a
+# source-file to every attached client immediately.
+tmux_dir="${XDG_CONFIG_HOME:-$HOME/.config}/tmux"
+tmux_theme="$tmux_dir/themes/tokyonight-moon.conf"
+[[ "$scheme" == "light" ]] && tmux_theme="$tmux_dir/themes/tokyonight-day.conf"
+
+status_tmux="skipped"
+if [[ -r "$tmux_theme" ]]; then
+    if cp "$tmux_theme" "$tmux_dir/current-theme.conf.tmp" 2>/dev/null \
+        && mv "$tmux_dir/current-theme.conf.tmp" "$tmux_dir/current-theme.conf" 2>/dev/null; then
+        status_tmux="written"
+        # Only if a server is actually running; `tmux source-file` would
+        # otherwise start one just to theme it.
+        if command -v tmux >/dev/null 2>&1 && tmux has-session 2>/dev/null; then
+            tmux source-file "$tmux_dir/current-theme.conf" 2>/dev/null \
+                && status_tmux="applied to running sessions"
+        fi
+    else
+        rm -f "$tmux_dir/current-theme.conf.tmp"
+        status_tmux="failed"
+    fi
+fi
+
+# ── btop ─────────────────────────────────────────────────────────────────────
+# Only the color_theme line is rewritten, in place. btop OWNS btop.conf -- it
+# rewrites the whole file on exit -- so the config is not symlinked into Panama
+# and not replaced wholesale here; just this one value is edited, and btop keeps
+# it on the next write.
+#
+# btop reads its theme once at startup, so a running instance keeps the old
+# colours until it is restarted. That is acceptable for a monitor you open when
+# you want it, and forcing a restart would kill a process the user is watching.
+btop_conf="${XDG_CONFIG_HOME:-$HOME/.config}/btop/btop.conf"
+btop_theme="tokyonight-moon"
+[[ "$scheme" == "light" ]] && btop_theme="tokyonight-day"
+
+status_btop="skipped"
+if [[ -w "$btop_conf" ]]; then
+    if sed -i "s|^color_theme *=.*|color_theme = \"$btop_theme\"|" "$btop_conf" 2>/dev/null; then
+        status_btop="written"
+    else
+        status_btop="failed"
+    fi
+fi
+
 # ── GTK ──────────────────────────────────────────────────────────────────────
 # adw-gtk3, not Adwaita: no Adwaita GTK theme is installed on Fedora 44, and
 # naming a theme that does not exist makes GTK fall back to its light default --
@@ -89,4 +137,13 @@ if [[ -r "$theme_file" ]]; then
     fi
 fi
 
-printf '{"scheme":"%s","kitty":"%s"}\n' "$scheme" "$status_kitty"
+# Every target reports what actually happened. A helper that says only
+# "kitty: applied" while silently skipping three other applications is how a
+# half-applied theme goes unnoticed.
+jq -cn \
+    --arg scheme "$scheme" \
+    --arg kitty "$status_kitty" \
+    --arg gtk "$status_gtk" \
+    --arg btop "$status_btop" \
+    --arg tmux "$status_tmux" \
+    '{scheme: $scheme, kitty: $kitty, gtk: $gtk, btop: $btop, tmux: $tmux}'

config/dot/quickshell/scripts/panama-wifi-qr

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+
+# A QR code for a saved Wi-Fi network, so a guest can join by pointing a camera.
+#
+# GNOME's Wi-Fi panel has this and it is the single most-used thing in it.
+# The payload is the de-facto WIFI: URI that Android and iOS both scan:
+#
+#   WIFI:T:WPA;S:<ssid>;P:<passphrase>;H:<hidden>;;
+#
+# HANDLING THE PASSPHRASE
+#
+# This image contains the network password in machine-readable form. Anyone who
+# can read the file can read the password, so:
+#
+#   * it is written under XDG_RUNTIME_DIR, which is 0700 and on tmpfs, so it
+#     never reaches disk and disappears at logout -- not /tmp, which is shared;
+#   * it is created with umask 077;
+#   * the passphrase is never printed, never passed as an argument (argv is
+#     world-readable via /proc), and never appears in an error message.
+#
+# It is piped to qrencode on stdin for that last reason.
+#
+# Usage:
+#   panama-wifi-qr list        -> {"networks":[{"name","ssid","shareable"}]}
+#   panama-wifi-qr qr <name>   -> {"path":"/run/user/…/….png"}
+
+set -uo pipefail
+
+emit_error() {
+    printf '{"networks":[],"path":"","error":%s}\n' "$(jq -Rn --arg e "$1" '$e')"
+    exit 0
+}
+
+command -v nmcli >/dev/null 2>&1 || emit_error 'NetworkManager is not available'
+command -v qrencode >/dev/null 2>&1 || emit_error 'qrencode is not installed, so a Wi-Fi QR code cannot be drawn'
+
+cmd_list() {
+    local rows=() name ssid psk
+    while IFS= read -r name; do
+        [[ -n "$name" ]] || continue
+        ssid="$(nmcli -g 802-11-wireless.ssid connection show "$name" 2>/dev/null)"
+        [[ -n "$ssid" ]] || ssid="$name"
+
+        # Only networks whose passphrase this user can actually read are
+        # shareable. An enterprise network has no passphrase to share at all,
+        # and a QR code for one would simply not work.
+        psk="$(nmcli -s -g 802-11-wireless-security.psk connection show "$name" 2>/dev/null)"
+
+        rows+=("$(jq -cn --arg name "$name" --arg ssid "$ssid" \
+            --argjson shareable "$([[ -n "$psk" ]] && echo true || echo false)" \
+            '{name: $name, ssid: $ssid, shareable: $shareable}')")
+    done < <(nmcli -t -f NAME,TYPE connection show 2>/dev/null \
+        | awk -F: '$2 == "802-11-wireless" { print $1 }')
+
+    if [[ ${#rows[@]} -eq 0 ]]; then
+        printf '{"networks":[],"path":"","error":"No saved Wi-Fi networks."}\n'
+        return 0
+    fi
+    printf '{"networks":[%s],"path":"","error":""}\n' "$(IFS=,; printf '%s' "${rows[*]}")"
+}
+
+# The WIFI: URI reserves \ ; , : and ", each escaped with a backslash. An SSID
+# containing a semicolon would otherwise terminate the field early and produce a
+# QR code for a different network entirely.
+#
+# Trailing newlines are stripped as well. nmcli terminates every value with one,
+# and left in place it lands INSIDE the payload -- the code still decodes here,
+# but a newline in the middle of a WIFI: URI is not something every phone's
+# scanner tolerates, and the failure would look like "the QR code just does not
+# work on my phone".
+escape_field() {
+    sed -e 's/\\/\\\\/g' -e 's/;/\\;/g' -e 's/,/\\,/g' -e 's/:/\\:/g' -e 's/"/\\"/g' \
+        | tr -d '\n'
+}
+
+cmd_qr() {
+    local name="${1:-}"
+    [[ -n "$name" ]] || emit_error 'no network named'
+
+    local ssid hidden psk_file payload_file out_dir out_file
+    ssid="$(nmcli -g 802-11-wireless.ssid connection show "$name" 2>/dev/null)"
+    [[ -n "$ssid" ]] || emit_error "There is no saved network called \"$name\"."
+
+    hidden="$(nmcli -g 802-11-wireless.hidden connection show "$name" 2>/dev/null)"
+    [[ "$hidden" == "yes" ]] && hidden=true || hidden=false
+
+    out_dir="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/panama"
+    umask 077
+    mkdir -p "$out_dir" 2>/dev/null || emit_error 'could not create the runtime directory'
+    chmod 700 "$out_dir" 2>/dev/null || true
+
+    # Named after the connection, hashed, so repeated shares reuse one file
+    # instead of accumulating images of the password.
+    out_file="$out_dir/wifi-$(printf '%s' "$name" | sha256sum | cut -c1-16).png"
+
+    # Built in a file rather than a variable that could be echoed, and piped to
+    # qrencode on stdin so the passphrase never appears in argv.
+    payload_file="$(mktemp "$out_dir/payload.XXXXXX")" || emit_error 'could not create a temporary file'
+    trap 'rm -f "$payload_file"' RETURN
+
+    {
+        printf 'WIFI:T:WPA;S:'
+        printf '%s' "$ssid" | escape_field
+        printf ';P:'
+        nmcli -s -g 802-11-wireless-security.psk connection show "$name" 2>/dev/null | escape_field
+        printf ';H:%s;;' "$hidden"
+    } >"$payload_file"
+
+    if ! qrencode -o "$out_file" -s 8 -m 2 -l M <"$payload_file" 2>/dev/null; then
+        emit_error "Could not generate a QR code for \"$name\"."
+    fi
+    chmod 600 "$out_file" 2>/dev/null || true
+
+    jq -cn --arg path "$out_file" '{networks: [], path: $path, error: ""}'
+}
+
+case "${1:-list}" in
+    list) cmd_list ;;
+    qr)   shift; cmd_qr "${1:-}" ;;
+    *)    printf 'usage: panama-wifi-qr [list|qr <name>]\n' >&2; exit 2 ;;
+esac

config/dot/quickshell/services/Connectivity.qml

@@ -33,11 +33,16 @@ Singleton {
     }
 
     readonly property var wiredDevice: {
+        let fallback = null;
         for (const device of Networking.devices.values) {
-            if (device.type === DeviceType.Wired)
+            if (device.type !== DeviceType.Wired)
+                continue;
+            if (device.connected)
                 return device;
+            if (!fallback)
+                fallback = device;
         }
-        return null;
+        return fallback;
     }
 
     readonly property var adapter: Bluetooth.defaultAdapter

config/dot/quickshell/services/Health.qml

@@ -0,0 +1,444 @@
+pragma Singleton
+
+// The health helper is deliberately not a state owner. This singleton accepts
+// complete, typed snapshots and keeps the last valid one available while a
+// later scan or repair fails.
+
+import Quickshell
+import Quickshell.Io
+import QtQuick
+
+Singleton {
+    id: root
+
+    property var snapshot: ({})
+    property var checks: []
+    property var summary: ({ status: "healthy", healthy: 0, warnings: 0, errors: 0, unconfigured: 0 })
+    property string status: "healthy"
+    property bool diagnosticUnavailable: false
+    property bool queuedRefresh: false
+    property int generation: 0
+    property int acceptedGeneration: 0
+    property string lastError: ""
+    property string repairingId: ""
+    property var lastRepair: ({})
+    property string lastCopyResult: ""
+    property bool startupScanEnabled: true
+    property bool postRepairScanPending: false
+
+    readonly property bool actionable: root.status === "warning" || root.status === "error"
+    readonly property bool busy: scanProcess.running || repairProcess.running || root.postRepairScanPending
+    readonly property string helperPath: Quickshell.env("PANAMA_HEALTH_HELPER")
+        || Quickshell.shellDir + "/scripts/panama-doctor"
+    readonly property var statuses: ["ok", "warning", "error", "unconfigured"]
+    readonly property var groups: ["desktop-foundation", "input-media", "integrations", "panama-tools"]
+    readonly property var overallStatuses: ["healthy", "warning", "error"]
+    readonly property var settingsTargets: ["home-phone", "datetime"]
+    readonly property var instructionTargets: ["ddc-permissions"]
+
+    Process {
+        id: scanProcess
+
+        property int scanGeneration: 0
+        property string outputText: ""
+        property int exitCode: -1
+        property bool exited: false
+        property bool streamFinished: false
+        property bool settled: false
+
+        stdout: StdioCollector {
+            id: scanOutput
+            property int generation: 0
+            onStreamFinished: {
+                scanProcess.outputText = this.text;
+                scanProcess.scanGeneration = generation;
+                scanProcess.streamFinished = true;
+                root.settleScan();
+            }
+        }
+
+        onExited: (exitCode, exitStatus) => {
+            scanProcess.exitCode = exitCode;
+            scanProcess.exited = true;
+            root.settleScan();
+        }
+    }
+
+    Process {
+        id: repairProcess
+
+        property string checkId: ""
+        property bool external: false
+        property string outputText: ""
+        property int exitCode: -1
+        property bool exited: false
+        property bool streamFinished: false
+        property bool settled: false
+
+        stdout: StdioCollector {
+            onStreamFinished: {
+                repairProcess.outputText = this.text;
+                repairProcess.streamFinished = true;
+                root.settleRepair();
+            }
+        }
+
+        onExited: (exitCode, exitStatus) => {
+            repairProcess.exitCode = exitCode;
+            repairProcess.exited = true;
+            root.settleRepair();
+        }
+    }
+
+    Process {
+        id: copyProcess
+
+        property string payload: ""
+
+        onStarted: copyProcess.write(copyProcess.payload)
+        onExited: (exitCode, exitStatus) => {
+            root.lastCopyResult = exitCode === 0
+                ? "Report copied."
+                : "Could not copy the health report."
+            copyProcess.payload = ""
+        }
+    }
+
+    Process {
+        id: failureNotification
+    }
+
+    Timer {
+        id: startupScan
+        interval: 2200
+        repeat: false
+        running: root.startupScanEnabled
+        onTriggered: root.refresh()
+    }
+
+    function refresh(): bool {
+        if (root.postRepairScanPending)
+            return false;
+        if (scanProcess.running || repairProcess.running) {
+            root.queuedRefresh = true;
+            return false;
+        }
+
+        root.generation += 1;
+        scanProcess.scanGeneration = root.generation;
+        scanProcess.outputText = "";
+        scanProcess.exitCode = -1;
+        scanProcess.exited = false;
+        scanProcess.streamFinished = false;
+        scanProcess.settled = false;
+        scanOutput.generation = root.generation;
+        scanProcess.exec([root.helperPath, "--json"]);
+        return true;
+    }
+
+    function settleScan(): void {
+        if (scanProcess.settled || !scanProcess.exited || !scanProcess.streamFinished)
+            return;
+        scanProcess.settled = true;
+        root.finishScan(scanProcess.exitCode, scanProcess.scanGeneration, scanProcess.outputText);
+    }
+
+    function finishScan(exitCode: int, scanGeneration: int, text: string): void {
+        if (exitCode === 0)
+            root.consumeSnapshot(text, scanGeneration);
+        else
+            root.rejectSnapshot("Panama diagnostics could not be read. Try refreshing.");
+
+        if (!root.queuedRefresh)
+            return;
+        root.queuedRefresh = false;
+        root.refresh();
+    }
+
+    function consumeSnapshot(text: string, scanGeneration: int): bool {
+        if (scanGeneration < root.acceptedGeneration)
+            return false;
+
+        let candidate;
+        try {
+            candidate = JSON.parse(text.trim());
+        } catch (error) {
+            root.rejectSnapshot("Panama diagnostics returned an unreadable response.");
+            return false;
+        }
+
+        if (!root.validSnapshot(candidate)) {
+            root.rejectSnapshot("Panama diagnostics returned an invalid response.");
+            return false;
+        }
+
+        const accepted = root.safeSnapshot(candidate);
+        root.snapshot = accepted;
+        root.checks = accepted.checks;
+        root.summary = accepted.summary;
+        root.status = accepted.summary.status;
+        root.acceptedGeneration = scanGeneration;
+        root.diagnosticUnavailable = false;
+        root.lastError = "";
+        return true;
+    }
+
+    function rejectSnapshot(message: string): void {
+        root.diagnosticUnavailable = true;
+        root.lastError = message;
+    }
+
+    function safeSnapshot(candidate: var): var {
+        return {
+            schemaVersion: 1,
+            generatedAt: candidate.generatedAt,
+            summary: {
+                status: candidate.summary.status,
+                healthy: candidate.summary.healthy,
+                warnings: candidate.summary.warnings,
+                errors: candidate.summary.errors,
+                unconfigured: candidate.summary.unconfigured
+            },
+            context: {
+                session: candidate.context.session,
+                versions: candidate.context.versions.map(version => ({
+                    id: version.id,
+                    version: version.version
+                }))
+            },
+            checks: candidate.checks.map(check => root.safeCheck(check))
+        };
+    }
+
+    function safeCheck(candidate: var): var {
+        const check = {
+            id: candidate.id,
+            group: candidate.group,
+            title: candidate.title,
+            status: candidate.status,
+            detail: candidate.detail
+        };
+        if (candidate.action !== undefined)
+            check.action = root.safeAction(candidate.action);
+        return check;
+    }
+
+    function safeAction(candidate: var): var {
+        const action = {
+            kind: candidate.kind,
+            label: candidate.label,
+            confirm: candidate.confirm
+        };
+        if (Object.prototype.hasOwnProperty.call(candidate, "target"))
+            action.target = candidate.target;
+        return action;
+    }
+
+    function repair(id: string, external: bool): bool {
+        if (root.busy)
+            return false;
+
+        const check = root.checks.find(candidate => candidate.id === id);
+        if (!check || !check.action || check.action.kind !== "repair")
+            return false;
+        if (external && check.action.confirm)
+            return false;
+
+        root.repairingId = id;
+        root.lastError = "";
+        repairProcess.checkId = id;
+        repairProcess.external = external;
+        repairProcess.outputText = "";
+        repairProcess.exitCode = -1;
+        repairProcess.exited = false;
+        repairProcess.streamFinished = false;
+        repairProcess.settled = false;
+        repairProcess.exec([root.helperPath, "--repair", id, "--json"]);
+        return true;
+    }
+
+    function settleRepair(): void {
+        if (repairProcess.settled || !repairProcess.exited || !repairProcess.streamFinished)
+            return;
+        repairProcess.settled = true;
+        root.finishRepair(
+            repairProcess.exitCode,
+            repairProcess.checkId,
+            repairProcess.external,
+            repairProcess.outputText
+        );
+    }
+
+    function finishRepair(exitCode: int, id: string, external: bool, text: string): void {
+        let candidate;
+        try {
+            candidate = JSON.parse(text.trim());
+        } catch (error) {
+            candidate = null;
+        }
+
+        const result = root.validRepairResult(candidate, id, exitCode)
+            ? {
+                schemaVersion: 1,
+                checkId: candidate.checkId,
+                accepted: candidate.accepted,
+                exitCode: candidate.exitCode,
+                message: candidate.message
+            }
+            : {
+                schemaVersion: 1,
+                checkId: id,
+                accepted: false,
+                exitCode: exitCode,
+                message: "Panama returned an invalid repair response."
+            };
+        const failed = !result.accepted || result.exitCode !== 0;
+        root.repairingId = "";
+        root.lastRepair = result;
+        root.lastError = failed ? result.message : "";
+        if (failed && external && !failureNotification.running) {
+                failureNotification.exec([
+                    "notify-send", "-a", "Panama", "-i", "dialog-error-symbolic",
+                    "Panama action failed", "The requested health repair could not be completed."
+                ]);
+        }
+
+        // Any refresh requested while the repair was running is satisfied by
+        // this one observed post-repair scan. Process exit alone never changes
+        // the accepted check rows.
+        root.queuedRefresh = false;
+        root.postRepairScanPending = true;
+        Qt.callLater(root.startPostRepairScan);
+    }
+
+    function startPostRepairScan(): void {
+        root.postRepairScanPending = false;
+        root.queuedRefresh = false;
+        root.refresh();
+    }
+
+    function validRepairResult(candidate: var, id: string, processExitCode: int): bool {
+        if (!root.plainObject(candidate))
+            return false;
+        const keys = Object.keys(candidate).sort();
+        const expectedKeys = ["accepted", "checkId", "exitCode", "message", "schemaVersion"];
+        if (keys.length !== expectedKeys.length
+                || !keys.every((key, index) => key === expectedKeys[index]))
+            return false;
+        return candidate.schemaVersion === 1
+            && candidate.checkId === id
+            && typeof candidate.accepted === "boolean"
+            && Number.isInteger(candidate.exitCode)
+            && candidate.exitCode === processExitCode
+            && typeof candidate.message === "string"
+            && candidate.message.length > 0;
+    }
+
+    function copyReport(): bool {
+        if (copyProcess.running)
+            return false;
+        copyProcess.payload = JSON.stringify(root.snapshot, null, 2);
+        root.lastCopyResult = "";
+        copyProcess.exec(["wl-copy"]);
+        return true;
+    }
+
+    function diagnostics(): var {
+        return {
+            status: root.status,
+            summary: root.summary,
+            busy: root.busy,
+            diagnosticUnavailable: root.diagnosticUnavailable,
+            queuedRefresh: root.queuedRefresh,
+            generation: root.generation,
+            acceptedGeneration: root.acceptedGeneration,
+            repairingId: root.repairingId,
+            lastRepair: root.lastRepair,
+            lastError: root.lastError,
+            checks: root.checks.map(check => check.id),
+            checkStates: root.checks.map(check => ({ id: check.id, status: check.status }))
+        };
+    }
+
+    function validSnapshot(candidate: var): bool {
+        if (!root.plainObject(candidate)
+                || candidate.schemaVersion !== 1
+                || typeof candidate.generatedAt !== "string" || candidate.generatedAt.length === 0
+                || !root.validSummary(candidate.summary)
+                || !root.validContext(candidate.context)
+                || !Array.isArray(candidate.checks) || candidate.checks.length === 0)
+            return false;
+
+        const ids = {};
+        const counts = { ok: 0, warning: 0, error: 0, unconfigured: 0 };
+        for (const check of candidate.checks) {
+            if (!root.validCheck(check) || ids[check.id])
+                return false;
+            ids[check.id] = true;
+            counts[check.status] += 1;
+        }
+
+        const computedStatus = counts.error > 0 ? "error" : counts.warning > 0 ? "warning" : "healthy";
+        return candidate.summary.healthy === counts.ok
+            && candidate.summary.warnings === counts.warning
+            && candidate.summary.errors === counts.error
+            && candidate.summary.unconfigured === counts.unconfigured
+            && candidate.summary.status === computedStatus;
+    }
+
+    function validSummary(candidate: var): bool {
+        if (!root.plainObject(candidate) || root.overallStatuses.indexOf(candidate.status) < 0)
+            return false;
+        for (const key of ["healthy", "warnings", "errors", "unconfigured"]) {
+            if (!Number.isInteger(candidate[key]) || candidate[key] < 0)
+                return false;
+        }
+        return true;
+    }
+
+    function validContext(candidate: var): bool {
+        if (!root.plainObject(candidate)
+                || ["hyprland", "other"].indexOf(candidate.session) < 0
+                || !Array.isArray(candidate.versions))
+            return false;
+        return candidate.versions.every(version => root.plainObject(version)
+            && typeof version.id === "string" && version.id.length > 0
+            && typeof version.version === "string" && version.version.length > 0);
+    }
+
+    function validCheck(candidate: var): bool {
+        if (!root.plainObject(candidate)
+                || !/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/.test(candidate.id)
+                || root.groups.indexOf(candidate.group) < 0
+                || root.statuses.indexOf(candidate.status) < 0
+                || typeof candidate.title !== "string" || candidate.title.length === 0
+                || typeof candidate.detail !== "string" || candidate.detail.length === 0)
+            return false;
+        return candidate.action === undefined || root.validAction(candidate.action);
+    }
+
+    function validAction(candidate: var): bool {
+        if (!root.plainObject(candidate)
+                || ["repair", "open", "instructions"].indexOf(candidate.kind) < 0
+                || typeof candidate.label !== "string" || candidate.label.length === 0
+                || typeof candidate.confirm !== "boolean")
+            return false;
+
+        const allowedKeys = ["kind", "label", "confirm", "target"];
+        if (!Object.keys(candidate).every(key => allowedKeys.indexOf(key) >= 0))
+            return false;
+
+        const hasTarget = Object.prototype.hasOwnProperty.call(candidate, "target");
+        if (!hasTarget)
+            return true;
+        if (typeof candidate.target !== "string" || candidate.target.length === 0 || candidate.kind === "repair")
+            return false;
+        return candidate.kind === "open"
+            ? root.settingsTargets.indexOf(candidate.target) >= 0
+            : root.instructionTargets.indexOf(candidate.target) >= 0;
+    }
+
+    function plainObject(value: var): bool {
+        return typeof value === "object" && value !== null && !Array.isArray(value);
+    }
+}

config/dot/quickshell/services/PowerProfiles.qml

@@ -0,0 +1,107 @@
+pragma Singleton
+
+// The system power profile: power-saver, balanced, or performance.
+//
+// The same daemon GNOME's Power panel drives. On Fedora 44 the implementation
+// is tuned-ppd rather than power-profiles-daemon, but it serves the same
+// net.hadess.PowerProfiles interface -- so this talks to the interface, not to
+// either binary. powerprofilesctl is not installed here at all.
+//
+// Not a stored preference. The profile lives in the daemon, survives Panama
+// restarts, and can be changed by anything else on the system; keeping a copy
+// in settings.json would mean restoring a value the daemon had moved past.
+// Same reasoning as monitor brightness.
+//
+// Read on demand and after each change. The daemon does emit PropertiesChanged,
+// but subscribing to it would mean holding a bus connection open for a value
+// that changes only when someone chooses it.
+
+import Quickshell
+import Quickshell.Io
+import QtQuick
+
+Singleton {
+    id: root
+
+    readonly property string helperPath: Quickshell.shellDir + "/scripts/panama-power-profile"
+
+    property var profiles: []
+    property string active: ""
+    property bool scanned: false
+    property bool busy: false
+    property string lastError: ""
+
+    // Non-empty when the machine cannot actually deliver the profile it is set
+    // to -- thermal throttling, or a laptop running on battery. Worth showing,
+    // because otherwise "performance" is a claim the hardware is not honouring.
+    property string degraded: ""
+
+    readonly property bool available: root.profiles.length > 0
+
+    // Presentation lives here rather than in the page so the Control Center and
+    // Settings cannot disagree about what a profile is called.
+    function label(profile: string): string {
+        switch (profile) {
+        case "power-saver": return "Power Saver";
+        case "balanced": return "Balanced";
+        case "performance": return "Performance";
+        default: return profile;
+        }
+    }
+
+    function detail(profile: string): string {
+        switch (profile) {
+        case "power-saver": return "Reduces performance to save energy and run quieter";
+        case "balanced": return "Standard behaviour, scaling up only when needed";
+        case "performance": return "Holds higher clocks, using more power and making more noise";
+        default: return "";
+        }
+    }
+
+    function refresh(): void {
+        if (!query.running)
+            query.running = true;
+    }
+
+    function set(profile: string): void {
+        if (root.busy || profile === root.active)
+            return;
+        root.busy = true;
+        apply.command = [root.helperPath, "set", profile];
+        apply.running = true;
+    }
+
+    Process {
+        id: query
+        command: [root.helperPath, "list"]
+        stdout: StdioCollector {
+            onStreamFinished: {
+                try {
+                    const parsed = JSON.parse(this.text);
+                    root.profiles = Array.isArray(parsed.profiles) ? parsed.profiles : [];
+                    root.active = String(parsed.active ?? "");
+                    root.degraded = String(parsed.degraded ?? "");
+                    root.lastError = String(parsed.error ?? "");
+                } catch (error) {
+                    root.profiles = [];
+                    root.lastError = "Could not read the power profile helper's output.";
+                    console.warn("PowerProfiles: could not parse helper output:", error);
+                }
+                root.scanned = true;
+            }
+        }
+    }
+
+    Process {
+        id: apply
+        stderr: StdioCollector {
+            onStreamFinished: if (this.text.trim() !== "") root.lastError = this.text.trim()
+        }
+        // Re-read rather than assuming: the daemon may refuse, or may land on a
+        // different profile than the one asked for.
+        onExited: {
+            root.busy = false;
+            root.refresh();
+        }
+    }
+}

config/dot/quickshell/services/SettingsSearch.qml

@@ -52,7 +52,9 @@ Singleton {
         { label: "Printers", detail: "Managed by GNOME Settings", page: "connectivity" },
         { label: "Default applications", detail: "Browser, mail, files", page: "applications" },
         { label: "Restore defaults", detail: "Return every Panama setting to its shipped value", page: "desktop" },
-        { label: "Keyboard shortcuts", detail: "Every shortcut the compositor has bound", page: "shortcuts" }
+        { label: "Keyboard shortcuts", detail: "Every shortcut the compositor has bound", page: "shortcuts" },
+        { label: "System Health", detail: "Check Panama services, integrations, tools, and recovery actions", page: "services" },
+        { label: "Copy health report", detail: "Copy a redacted Panama doctor report", page: "services" }
     ]
 
     function pageFor(group: string): string {

config/dot/quickshell/services/WifiShare.qml

@@ -0,0 +1,99 @@
+pragma Singleton
+
+// A QR code for a saved Wi-Fi network, so a guest can join by pointing a phone
+// at the screen. GNOME's Wi-Fi panel has this and it is the most-used thing in
+// it; reading a passphrase aloud is the alternative.
+//
+// The generated image contains the network password in machine-readable form,
+// so the helper writes it under XDG_RUNTIME_DIR -- 0700, on tmpfs, gone at
+// logout -- rather than anywhere persistent. Nothing here ever holds the
+// passphrase itself; this service only ever sees a file path.
+//
+// Generated on demand. Producing a QR for every saved network up front would
+// mean writing images of passwords nobody asked to see.
+
+import Quickshell
+import Quickshell.Io
+import QtQuick
+
+Singleton {
+    id: root
+
+    readonly property string helperPath: Quickshell.shellDir + "/scripts/panama-wifi-qr"
+
+    // [{ name, ssid, shareable }]
+    property var networks: []
+    property bool scanned: false
+    property string lastError: ""
+
+    // The network whose code is on screen, and where its image is. Empty when
+    // nothing is being shared.
+    property string sharing: ""
+    property string imagePath: ""
+
+    readonly property var shareable: root.networks.filter(n => n.shareable)
+
+    function refresh(): void {
+        if (!list.running)
+            list.running = true;
+    }
+
+    function share(name: string): void {
+        if (generate.running)
+            return;
+        // Cache-bust: the helper reuses one file per network, so a QML Image
+        // pointed at the same path would keep showing the previous render.
+        root.imagePath = "";
+        root.sharing = name;
+        generate.command = [root.helperPath, "qr", name];
+        generate.running = true;
+    }
+
+    function stopSharing(): void {
+        root.sharing = "";
+        root.imagePath = "";
+    }
+
+    Process {
+        id: list
+        command: [root.helperPath, "list"]
+        stdout: StdioCollector {
+            onStreamFinished: {
+                try {
+                    const parsed = JSON.parse(this.text);
+                    root.networks = Array.isArray(parsed.networks) ? parsed.networks : [];
+                    root.lastError = String(parsed.error ?? "");
+                } catch (error) {
+                    root.networks = [];
+                    root.lastError = "Could not read the Wi-Fi helper's output.";
+                    console.warn("WifiShare: could not parse helper output:", error);
+                }
+                root.scanned = true;
+            }
+        }
+    }
+
+    Process {
+        id: generate
+        stdout: StdioCollector {
+            onStreamFinished: {
+                try {
+                    const parsed = JSON.parse(this.text);
+                    const path = String(parsed.path ?? "");
+                    const error = String(parsed.error ?? "");
+                    if (error !== "" || path === "") {
+                        root.lastError = error !== "" ? error : "No QR code was produced.";
+                        root.sharing = "";
+                        return;
+                    }
+                    root.lastError = "";
+                    root.imagePath = path;
+                } catch (error) {
+                    root.lastError = "Could not read the generated QR code's path.";
+                    root.sharing = "";
+                    console.warn("WifiShare: could not parse helper output:", error);
+                }
+            }
+        }
+    }
+}

config/dot/quickshell/shell.qml

@@ -145,6 +145,26 @@ ShellRoot {
         }
     }
 
+    IpcHandler {
+        target: "health"
+
+        function refresh(): bool { return Health.refresh(); }
+        function status(): string {
+            return JSON.stringify({
+                summary: Health.summary,
+                busy: Health.busy,
+                generation: Health.generation,
+                acceptedGeneration: Health.acceptedGeneration,
+                checks: Health.checks.map(check => ({ id: check.id, status: check.status }))
+            });
+        }
+        function open(): void {
+            ShellState.openSettings("services");
+            Health.refresh();
+        }
+        function repair(id: string): bool { return Health.repair(id, true); }
+    }
+
     // A small diagnostics surface doubles as a deterministic contract harness.
     // Real producers call StatusEvents.publish() directly; fixtures never run
     // unless explicitly requested over IPC by the test suite.

config/dot/tmux/themes/tokyonight-day.conf

@@ -0,0 +1,30 @@
+# Tokyo Night Day for tmux -- the light counterpart to tokyonight-moon.conf.
+#
+# Same structure, same roles, Day's palette. Mapped role for role rather than by
+# hue: #1b1d2b was text drawn ON an accent block, so it becomes the LIGHT ground
+# rather than a dark colour, or the status bar would be dark text on a dark
+# accent in light mode.
+#
+# The accents are Day's DARKER variants, not its standard ones. Measured against
+# the panel, the standard #2e7de9 and #9854f1 give 2.74:1 and 2.94:1 -- under
+# the 3:1 floor for text. These give 4.42:1 and 4.17:1, and 5.01:1 / 4.73:1 for
+# the light text drawn on top of them in the inverted blocks.
+
+set -g mode-style "fg=#1c5bb8,bg=#d0d5e3"
+
+set -g message-style "fg=#1c5bb8,bg=#d0d5e3"
+set -g message-command-style "fg=#1c5bb8,bg=#d0d5e3"
+
+set -g pane-border-style "fg=#1c5bb8"
+set -g pane-active-border-style "fg=#7847bd"
+
+set -g status-style "fg=#7847bd,bg=#d0d5e3"
+set -g status-bg "#e1e2e7"
+
+set -g status-left "#[fg=#e1e2e7,bg=#7847bd,bold] #S #[fg=#e1e2e7,bg=#7847bd,nobold,nounderscore,noitalics]"
+set -g status-right "#[fg=#e1e2e7,bg=#1c5bb8,nobold,nounderscore,noitalics]#[fg=#7847bd,bg=#d0d5e3] #{prefix_highlight} #[fg=#d0d5e3,bg=#d0d5e3]#[fg=#7847bd,bg=#d0d5e3] %Y/%m/%d  %I:%M %p #[fg=#1c5bb8,bg=#d0d5e3,nobold,nounderscore,noitalics]#[fg=#e1e2e7,bg=#7847bd,bold,italics] #h "
+
+setw -g window-status-format "#[fg=#e1e2e7,bg=#d0d5e3,nobold,nounderscore,noitalics]#[fg=#1c5bb8,bg=#d0d5e3] #I  #W #F #[fg=#e1e2e7,bg=#d0d5e3,nobold,nounderscore,noitalics]"
+setw -g window-status-current-format "#[fg=#e1e2e7,bg=#d0d5e3,nobold,nounderscore,noitalics]#[fg=#7847bd,bg=#d0d5e3,bold] #I  #W #F #[fg=#d0d5e3,bg=#d0d5e3,nobold,nounderscore,noitalics]"
+
+setw -g window-status-separator ""

config/dot/tmux/themes/tokyonight-moon.conf

@@ -0,0 +1,25 @@
+# Tokyo Night Moon for tmux -- the palette Panama ships.
+#
+# Extracted from tmux.conf so the two schemes can be swapped. tmux.conf sources
+# current-theme.conf, which panama-theme-apps generates from one of these.
+#
+# Every colour here was already in tmux.conf; this file is that block verbatim.
+
+set -g mode-style "fg=#82aaff,bg=#3b4261"
+
+set -g message-style "fg=#82aaff,bg=#3b4261"
+set -g message-command-style "fg=#82aaff,bg=#3b4261"
+
+set -g pane-border-style "fg=#82aaff"
+set -g pane-active-border-style "fg=#b172b0"
+
+set -g status-style "fg=#b172b0,bg=#3b4261"
+set -g status-bg "#222436"
+
+set -g status-left "#[fg=#1b1d2b,bg=#b172b0,bold] #S #[fg=#1b1d2b,bg=#b172b0,nobold,nounderscore,noitalics]"
+set -g status-right "#[fg=#1b1d2b,bg=#82aaff,nobold,nounderscore,noitalics]#[fg=#b172b0,bg=#3b4261] #{prefix_highlight} #[fg=#3b4261,bg=#3b4261]#[fg=#b172b0,bg=#3b4261] %Y/%m/%d  %I:%M %p #[fg=#82aaff,bg=#3b4261,nobold,nounderscore,noitalics]#[fg=#1b1d2b,bg=#b172b0,bold,italics] #h "
+
+setw -g window-status-format "#[fg=#1b1d2b,bg=#3b4261,nobold,nounderscore,noitalics]#[fg=#82aaff,bg=#3b4261] #I  #W #F #[fg=#1b1d2b,bg=#3b4261,nobold,nounderscore,noitalics]"
+setw -g window-status-current-format "#[fg=#1b1d2b,bg=#3b4261,nobold,nounderscore,noitalics]#[fg=#b172b0,bg=#3b4261,bold] #I  #W #F #[fg=#3b4261,bg=#3b4261,nobold,nounderscore,noitalics]"
+
+setw -g window-status-separator ""

config/dot/tmux/tmux.conf

@@ -19,24 +19,10 @@ bind C-Space send-prefix
 # Set status bar
 #set -g status-bg pink
 # Tokyo Night Moon color palette
-set -g mode-style "fg=#82aaff,bg=#3b4261"
+# Colours live in themes/ and are generated into current-theme.conf by
-
+# panama-theme-apps, which regenerates it whenever the desktop colour scheme
-set -g message-style "fg=#82aaff,bg=#3b4261"
+# changes. -q so a fresh checkout without the generated file still starts.
-set -g message-command-style "fg=#82aaff,bg=#3b4261"
+source-file -q "~/.config/tmux/current-theme.conf"
-
-set -g pane-border-style "fg=#82aaff"
-set -g pane-active-border-style "fg=#b172b0"
-
-set -g status-style "fg=#b172b0,bg=#3b4261"
-set -g status-bg "#222436"
-
-set -g status-left "#[fg=#1b1d2b,bg=#b172b0,bold] #S #[fg=#1b1d2b,bg=#b172b0,nobold,nounderscore,noitalics]"
-set -g status-right "#[fg=#1b1d2b,bg=#82aaff,nobold,nounderscore,noitalics]#[fg=#b172b0,bg=#3b4261] #{prefix_highlight} #[fg=#3b4261,bg=#3b4261]#[fg=#b172b0,bg=#3b4261] %Y/%m/%d  %I:%M %p #[fg=#82aaff,bg=#3b4261,nobold,nounderscore,noitalics]#[fg=#1b1d2b,bg=#b172b0,bold,italics] #h "
-
-setw -g window-status-format "#[fg=#1b1d2b,bg=#3b4261,nobold,nounderscore,noitalics]#[fg=#82aaff,bg=#3b4261] #I  #W #F #[fg=#1b1d2b,bg=#3b4261,nobold,nounderscore,noitalics]"
-setw -g window-status-current-format "#[fg=#1b1d2b,bg=#3b4261,nobold,nounderscore,noitalics]#[fg=#b172b0,bg=#3b4261,bold] #I  #W #F #[fg=#3b4261,bg=#3b4261,nobold,nounderscore,noitalics]"
-
-setw -g window-status-separator ""
 
 # Increase scrollback buffer
 set -g history-limit 50000

config/local/share/vicinae/scripts/check-system-health.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# @vicinae.schemaVersion 1
+# @vicinae.title Panama: Check System Health
+# @vicinae.mode silent
+# @vicinae.icon ../../icons/hicolor/scalable/apps/panama-settings.svg
+# @vicinae.description Review Panama services, integrations, and recovery actions.
+# @vicinae.keywords ["health", "doctor", "repair", "services"]
+
+exec "$HOME/.config/quickshell/scripts/panama-action" health

docs/superpowers/plans/2026-08-18-panama-health-recovery.md

@@ -0,0 +1,598 @@
+# Panama Health & Recovery Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a quiet, trustworthy System Health surface that diagnoses Panama-owned desktop functionality, exposes redacted reports, and offers only narrow allow-listed repairs.
+
+**Architecture:** An executable Python helper, `panama-doctor`, is the only operating-system boundary and emits one deterministic JSON schema. A `Health.qml` singleton owns accepted snapshots, scan generations, repair state, and report copying; Settings, the bar, IPC, and Vicinae consume that typed state without constructing commands.
+
+**Tech Stack:** Python 3 standard library, Bash contract tests, Quickshell/QML, QtQuick, Hyprland IPC, Vicinae script commands, Prism design tokens.
+
+**Spec:** `docs/superpowers/specs/2026-08-18-panama-health-recovery-design.md`
+
+## Global Constraints
+
+- Healthy background scans are silent: no notifications, Signal Glass events, animations, or permanent bar ornament.
+- Allowed statuses are exactly `ok`, `warning`, `error`, and `unconfigured`; overall status is `healthy`, `warning`, or `error`.
+- Optional integrations that have never been configured are `unconfigured`, never warnings.
+- The helper never reads or reports secret values, clipboard contents, notification bodies, calendar event data, SSIDs, addresses, or arbitrary command output.
+- The helper never installs packages, invokes `sudo`, deletes user data, rewrites arbitrary configuration, or repairs services Panama does not own.
+- Probe-derived values may populate observations only; check IDs, groups, titles, actions, commands, and arguments are authored constants.
+- All process launches use argument arrays. UI text and report content never become commands.
+- Preserve the last valid snapshot on helper failure or malformed JSON.
+- Repairs are judged by a fresh observed scan, not by process exit status alone.
+- Do not run a state-changing live repair without a genuinely degraded disposable target or explicit user approval.
+
+## File map and stable interfaces
+
+- `config/dot/quickshell/scripts/panama-doctor`: Python CLI and sole diagnostic/repair OS boundary.
+- `config/dot/quickshell/services/Health.qml`: snapshot state machine, scan/repair processes, report copy, and fixture seams.
+- `config/dot/quickshell/health-harness.qml`: deterministic IPC harness for generations, malformed data, coalescing, and repairs.
+- `config/dot/quickshell/modules/settings/HealthPage.qml`: System Health page composition.
+- `config/dot/quickshell/modules/settings/HealthSummary.qml`: stable-height summary hero and primary controls.
+- `config/dot/quickshell/modules/settings/HealthCheckRow.qml`: one accessible check row with one action.
+- `config/dot/quickshell/modules/bar/HealthIndicator.qml`: degraded-only bar entry point.
+- `config/local/share/vicinae/scripts/check-system-health.sh`: searchable launcher command.
+- `tests/quickshell/fixtures/doctor/`: isolated command, config, state, and runtime fixtures containing no real workstation data.
+- `tests/quickshell/panama-doctor-contract.sh`: schema, status, redaction, timeout, ordering, and repair allow-list contract.
+- `tests/quickshell/health-service-contract.sh`: QML state-machine contract.
+- `tests/quickshell/health-ui-contract.sh`: Settings, footer, report, indicator, IPC, and Vicinae integration contract.
+
+The helper's authored check order is:
+
+```text
+desktop.hyprland
+desktop.quickshell
+desktop.notifications
+desktop.portals
+desktop.hyprpaper
+desktop.hypridle
+desktop.vicinae
+input.pipewire
+input.clipboard
+input.wallpaper
+input.capture
+input.ocr
+input.brightness
+integration.nextcloud
+integration.rustdesk
+integration.kdeconnect
+integration.bluebubbles
+integration.home-assistant
+integration.calendar
+panama.runtime-links
+panama.vicinae-commands
+panama.selected-terminal
+panama.selected-launcher
+panama.processes
+panama.caffeine
+```
+
+Only these repair IDs are executable in release one:
+
+```text
+desktop.hyprpaper        -> systemctl --user restart hyprpaper.service
+desktop.hypridle         -> systemctl --user restart hypridle.service
+desktop.vicinae          -> systemctl --user restart vicinae.service
+desktop.quickshell       -> panama-action restart-shell (confirmation required)
+panama.runtime-links     -> recreate only known Panama-owned broken symlinks
+panama.vicinae-commands  -> setup/scripts/link-vicinae-scripts
+panama.caffeine          -> release duplicate Panama/Caffeine inhibitor PIDs only
+```
+
+---
+
+### Task 1: Prism health mocks and visual approval
+
+**Approved visual:** A — Diagnostic Ledger. Preserve its restrained issue rail, stable summary hero, two-column healthy ledgers, live sidebar footer, and degraded-only bar capsule.
+
+**Files:**
+- Create outside tracked source: `.superpowers/mocks/system-health/index.html`
+- Create outside tracked source: `.superpowers/mocks/system-health/panama.css`
+- Create outside tracked source: `.superpowers/mocks/system-health/mock.js`
+- Create outside tracked source: `.superpowers/mocks/system-health/a-ledger.html`
+- Create outside tracked source: `.superpowers/mocks/system-health/b-focus.html`
+- Create outside tracked source: `.superpowers/mocks/system-health/c-compact.html`
+
+**Interfaces:**
+- Consumes: the existing 272 px Settings sidebar, 48 px titlebar, Tokyo Night Moon Prism tokens, and the approved information architecture.
+- Produces: one approved visual composition for healthy, warning, checking, and error states plus the degraded-only bar indicator.
+
+- [ ] **Step 1: Build three static compositions from real copy**
+
+Use the same warning fixture in all three: `Vicinae` is stopped with action `Restart Vicinae`; `External monitor brightness` needs permission with action `View setup instructions`; `BlueBubbles` is `Not set up`. Keep every variant inside the real Settings geometry and include the footer and bar indicator.
+
+```text
+A — Diagnostic ledger: one restrained amber issue rail beside calm grouped rows.
+B — Focus card: issues receive the visual focus; healthy groups collapse into quieter ledgers below.
+C — Compact matrix: dense two-column group cards with the same issue-first ordering.
+```
+
+- [ ] **Step 2: Serve and visually inspect the mocks**
+
+Run:
+
+```bash
+python3 -m http.server 52780 --directory .superpowers/mocks/system-health
+```
+
+Expected: all three variants render at `http://localhost:52780`, keyboard focus is visible, no element overflows at 1360x900, and reduced-motion mode has no continuous animation.
+
+- [ ] **Step 3: Capture the approved direction in the plan**
+
+Add a short `Approved visual: <variant>` note beneath this task after user selection. Production UI work in Task 4 must reproduce that composition using existing QML tokens rather than copying browser-only effects.
+
+### Task 2: Deterministic read-only doctor
+
+**Files:**
+- Create: `config/dot/quickshell/scripts/panama-doctor`
+- Create: `tests/quickshell/panama-doctor-contract.sh`
+- Create: `tests/quickshell/fixtures/doctor/bin/systemctl`
+- Create: `tests/quickshell/fixtures/doctor/bin/pgrep`
+- Create: `tests/quickshell/fixtures/doctor/bin/busctl`
+- Create: `tests/quickshell/fixtures/doctor/bin/qs`
+- Create: `tests/quickshell/fixtures/doctor/bin/vicinae`
+- Create: `tests/quickshell/fixtures/doctor/bin/systemd-inhibit`
+
+**Interfaces:**
+- Consumes: `PANAMA_DOCTOR_ROOT`, `PANAMA_DOCTOR_HOME`, `PANAMA_DOCTOR_CONFIG_HOME`, `PANAMA_DOCTOR_STATE_HOME`, `PANAMA_DOCTOR_RUNTIME_DIR`, `PANAMA_DOCTOR_PATH`, and `PANAMA_DOCTOR_TIMEOUT` test seams; production defaults resolve from the real process environment.
+- Produces: `panama-doctor --json`, `panama-doctor --summary`, and a versioned schema with `summary` plus the 25 ordered check objects listed above.
+
+- [ ] **Step 1: Write the failing schema and redaction contract**
+
+The contract must create an isolated home, tracked source tree, runtime tree, and fake command directory, then assert:
+
+```bash
+snapshot="$($doctor --json)"
+jq -e '.schemaVersion == 1
+  and (.generatedAt | type == "string")
+  and (.summary.status | IN("healthy", "warning", "error"))
+  and (.context.session | IN("hyprland", "other"))
+  and (.context.versions | type == "array")
+  and ([.checks[].id] | length == 25)
+  and ([.checks[].id] | unique | length == 25)
+  and ([.checks[].status] | all(IN("ok", "warning", "error", "unconfigured")))' <<<"$snapshot"
+[[ "$(jq -r '.checks[].id' <<<"$snapshot")" == "$expected_order" ]]
+! grep -Fq 'fixture-secret-token' <<<"$snapshot"
+! grep -Fq 'fixture clipboard body' <<<"$snapshot"
+! grep -Fq 'AA:BB:CC:DD:EE:FF' <<<"$snapshot"
+```
+
+Cover a healthy required service, a missing required executable, an unconfigured optional integration, a configured-but-stopped integration, an inaccessible DDC bus, a timed-out probe, duplicate Caffeine inhibitors, malformed probe output, and concise `--summary` output.
+
+- [ ] **Step 2: Run the contract and verify the helper is absent**
+
+Run: `tests/quickshell/panama-doctor-contract.sh`
+
+Expected: FAIL because `config/dot/quickshell/scripts/panama-doctor` does not exist.
+
+- [ ] **Step 3: Implement authored checks and concurrent bounded probes**
+
+Use Python standard-library types and deterministic assembly:
+
+```python
+@dataclass(frozen=True)
+class Action:
+    kind: Literal["repair", "open", "instructions"]
+    label: str
+    confirm: bool = False
+
+@dataclass(frozen=True)
+class Check:
+    id: str
+    group: Literal["desktop-foundation", "input-media", "integrations", "panama-tools"]
+    title: str
+    status: Literal["ok", "warning", "error", "unconfigured"]
+    detail: str
+    action: Action | None = None
+```
+
+Run independent probes through `ThreadPoolExecutor(max_workers=8)`. Every subprocess call must use a constant argument tuple, `capture_output=True`, `text=True`, and the configured timeout. Convert timeout, non-zero status, and parse failure into a check result. Assemble checks by the authored ID tuple after futures settle; never emit completion order.
+
+Configuration checks may inspect existence and file type only. Home Assistant is configured when both expected variable names are present, but their values are never retained. Calendar is configured from enabled EDS source count only; event commands are never called. BlueBubbles is configured from the Flatpak installation check. DDC uses only `panama-brightness list` and retains display count plus its authored error classification, never connector names.
+
+The top-level `context` contains only an authored session class and an ordered array of parsed Hyprland, Quickshell, Fedora, and Panama revision versions. `panama.processes` counts only exact authored process names and flags duplicate Quickshell, Vicinae, Hyprpaper, or Hypridle instances without exposing command lines. Integration actions are authored too: Nextcloud, RustDesk, KDE Connect, and BlueBubbles may offer their exact Open action; Home Assistant and calendar failures route to `home-phone` and `datetime`; never derive an application or page name from probe output.
+
+- [ ] **Step 4: Run the doctor contract**
+
+Run: `tests/quickshell/panama-doctor-contract.sh`
+
+Expected: `panama doctor contract: PASS`.
+
+- [ ] **Step 5: Commit the read-only engine**
+
+```bash
+git add config/dot/quickshell/scripts/panama-doctor tests/quickshell/panama-doctor-contract.sh tests/quickshell/fixtures/doctor
+git commit -m "Add Panama system health diagnostics"
+```
+
+### Task 3: Health singleton and typed IPC state machine
+
+**Files:**
+- Create: `config/dot/quickshell/services/Health.qml`
+- Create: `config/dot/quickshell/health-harness.qml`
+- Create: `tests/quickshell/health-service-contract.sh`
+- Modify: `config/dot/quickshell/shell.qml`
+
+**Interfaces:**
+- Consumes: `panama-doctor --json` and `panama-doctor --repair CHECK_ID --json`.
+- Produces: `Health.snapshot`, `Health.checks`, `Health.summary`, `Health.status`, `Health.actionable`, `Health.busy`, `Health.diagnosticUnavailable`, `Health.lastError`, `Health.repairingId`, `Health.lastRepair`, `Health.lastCopyResult`, `Health.refresh()`, `Health.repair(id, external)`, `Health.copyReport()`, and IPC target `health` with `refresh`, `status`, `open`, and `repair(id)`.
+
+- [ ] **Step 1: Write the failing QML state contract**
+
+The harness exposes fixture methods that call the real singleton's pure consumption seams:
+
+```qml
+function accept(text: string, generation: int): bool { return Health.consumeSnapshot(text, generation); }
+function queue(): void { Health.refresh(); Health.refresh(); }
+function status(): string { return JSON.stringify(Health.diagnostics()); }
+```
+
+Assert that a valid warning snapshot is accepted, an older generation is ignored, malformed JSON preserves the prior checks and marks the engine unavailable, two refreshes while running schedule exactly one follow-up, a valid repair triggers one rescan, and unknown/non-repairable IDs start no process.
+
+- [ ] **Step 2: Run the contract and verify it fails**
+
+Run: `tests/quickshell/health-service-contract.sh`
+
+Expected: FAIL because `Health.qml` and the harness do not exist.
+
+- [ ] **Step 3: Implement the singleton state machine**
+
+Define the stable state shape:
+
+```qml
+property var snapshot: ({})
+property var checks: []
+property var summary: ({ status: "healthy", healthy: 0, warnings: 0, errors: 0, unconfigured: 0 })
+property string status: "healthy"
+property bool diagnosticUnavailable: false
+property bool queuedRefresh: false
+property int generation: 0
+property int acceptedGeneration: 0
+property string repairingId: ""
+property var lastRepair: ({})
+property string lastCopyResult: ""
+readonly property bool actionable: status === "warning" || status === "error"
+readonly property bool busy: scanProcess.running || repairProcess.running
+```
+
+Use `Process.exec([root.helperPath, "--json"])`; attach the current generation to the collector before launch. `consumeSnapshot(text, generation)` validates schema version, summary keys, context shape, unique IDs, groups, statuses, titles, details, and action shapes before replacing state. A 2200 ms one-shot startup timer requests the initial scan. A running scan sets `queuedRefresh`; exit consumes at most one queued follow-up. `copyReport()` sends only `JSON.stringify(root.snapshot, null, 2)` to `wl-copy` through a `Process` stdin buffer and writes success or failure to `lastCopyResult` without touching the clipboard service's history model.
+
+The `health` IPC `status()` returns only the already-redacted summary, busy flags, generation, and check IDs/statuses. `open()` calls `ShellState.openSettings("services")` then refreshes. IPC `repair(id)` calls `Health.repair(id, true)` and returns a Boolean acceptance result; Settings calls `Health.repair(id, false)`. A failed externally-originated repair uses an argument-array `notify-send` process with the existing `Panama action failed` title, while Settings failures remain inline.
+
+- [ ] **Step 4: Run service and IPC contracts**
+
+Run:
+
+```bash
+tests/quickshell/health-service-contract.sh
+tests/quickshell/settings-window-contract.sh
+```
+
+Expected: both PASS.
+
+- [ ] **Step 5: Commit the service layer**
+
+```bash
+git add config/dot/quickshell/services/Health.qml config/dot/quickshell/health-harness.qml tests/quickshell/health-service-contract.sh config/dot/quickshell/shell.qml
+git commit -m "Add Panama health state service"
+```
+
+### Task 4: Approved System Health Settings page
+
+**Files:**
+- Create: `config/dot/quickshell/modules/settings/HealthPage.qml`
+- Create: `config/dot/quickshell/modules/settings/HealthSummary.qml`
+- Create: `config/dot/quickshell/modules/settings/HealthCheckRow.qml`
+- Modify: `config/dot/quickshell/modules/settings/SettingsShell.qml`
+- Modify: `config/dot/quickshell/modules/settings/SettingsSidebar.qml`
+- Modify: `config/dot/quickshell/services/SettingsSearch.qml`
+- Delete: `config/dot/quickshell/modules/settings/ServicesPage.qml`
+- Create: `tests/quickshell/health-ui-contract.sh`
+- Modify: `tests/quickshell/settings-pages-contract.sh`
+- Modify: `tests/quickshell/settings-search-contract.sh`
+
+**Interfaces:**
+- Consumes: all read-only state and methods from `Health.qml`; route remains the stable internal name `services`.
+- Produces: System Health summary, issues-first cards, four grouped ledgers, live clickable sidebar footer, Copy Report feedback, and confirmation requests for disruptive repairs.
+
+- [ ] **Step 1: Write failing Settings and accessibility assertions**
+
+Assert static structure and fixture-rendered state:
+
+```bash
+rg -Fq 'label: "System Health"' config/dot/quickshell/modules/settings/SettingsSidebar.qml
+rg -Fq 'onClicked: Health.copyReport()' config/dot/quickshell/modules/settings/HealthSummary.qml
+rg -Fq 'onTapped: root.pageRequested("services")' config/dot/quickshell/modules/settings/SettingsSidebar.qml
+rg -Fq 'text: "Checking…"' config/dot/quickshell/modules/settings/HealthSummary.qml
+rg -Fq 'Health.refresh()' config/dot/quickshell/modules/settings/HealthPage.qml
+```
+
+The runtime harness must prove warning rows appear before healthy groups, unconfigured is visible as `Not set up`, every status has text in addition to color, refresh preserves row geometry, keyboard focus reaches both hero actions and row actions, and a Quickshell-restart repair opens a confirmation sheet.
+
+- [ ] **Step 2: Run UI contracts and verify failure**
+
+Run:
+
+```bash
+tests/quickshell/health-ui-contract.sh
+tests/quickshell/settings-pages-contract.sh
+tests/quickshell/settings-search-contract.sh
+```
+
+Expected: FAIL because the approved Health components are absent.
+
+- [ ] **Step 3: Implement the approved composition**
+
+Use `SettingsPage`, `SettingsCard`, `SettingsButton`, `Theme`, and `PrismEdge`. Keep the summary hero stable at 126 px and each check row at least 62 px. Derive labels exactly:
+
+```qml
+function statusLabel(status: string): string {
+    if (status === "ok") return "Healthy";
+    if (status === "warning") return "Needs attention";
+    if (status === "error") return "Action required";
+    return "Not set up";
+}
+```
+
+`HealthPage.Component.onCompleted` calls `Health.refresh()`. Issues are checks with `warning` or `error`. Group cards preserve helper order. Each row exposes at most one action. `open` actions route to exact Settings pages; `instructions` actions reveal authored inline instructions; `repair` actions call `Health.repair(id, false)` after confirmation only when `action.confirm === true`.
+
+The sidebar footer is a 54 px `TapHandler` target with status text derived from Health, not a hardcoded string. It opens `services`; when no scan has completed it says `Checking Panama desktop`. A malformed or failed doctor run retains the last rows, changes only the hero to `Health check unavailable`, and exposes one bounded `Retry` action. The page ends with the approved boundary note and an `Open GNOME Settings` action for networking, printers, users, and other Fedora-owned areas.
+
+- [ ] **Step 4: Run UI contracts and inspect the rendered fixture**
+
+Run:
+
+```bash
+tests/quickshell/health-ui-contract.sh
+tests/quickshell/settings-pages-contract.sh
+tests/quickshell/settings-search-contract.sh
+```
+
+Expected: all PASS with zero QML warnings.
+
+- [ ] **Step 5: Commit the Settings experience**
+
+```bash
+git add config/dot/quickshell/modules/settings config/dot/quickshell/services/SettingsSearch.qml tests/quickshell/health-ui-contract.sh tests/quickshell/settings-pages-contract.sh tests/quickshell/settings-search-contract.sh
+git commit -m "Build the System Health settings page"
+```
+
+### Task 5: Quiet bar indicator and launcher entry point
+
+**Files:**
+- Create: `config/dot/quickshell/modules/bar/HealthIndicator.qml`
+- Modify: `config/dot/quickshell/modules/bar/Bar.qml`
+- Create: `config/local/share/vicinae/scripts/check-system-health.sh`
+- Modify: `config/dot/quickshell/scripts/panama-action`
+- Modify: `tests/quickshell/health-ui-contract.sh`
+- Modify: `tests/quickshell/panama-action-contract.sh`
+- Modify: `tests/quickshell/panama-commands-contract.sh`
+
+**Interfaces:**
+- Consumes: `Health.actionable`, `Health.status`, and `Health.summary`; existing `panama-action` dispatcher and Settings IPC.
+- Produces: one degraded-only bar affordance and Vicinae command `Panama: Check System Health`.
+
+- [ ] **Step 1: Extend contracts before production files**
+
+Assert the indicator is absent for healthy/unconfigured-only fixtures, visible amber for warnings, visible red for errors, includes a textual accessible label, and opens `services`. Extend command fixtures so:
+
+```text
+panama-action health -> qs ipc call health open
+check-system-health.sh title -> Panama: Check System Health
+check-system-health.sh exec -> $HOME/.config/quickshell/scripts/panama-action health
+```
+
+- [ ] **Step 2: Run focused tests and verify failure**
+
+Run:
+
+```bash
+tests/quickshell/health-ui-contract.sh
+tests/quickshell/panama-action-contract.sh
+tests/quickshell/panama-commands-contract.sh
+```
+
+Expected: FAIL on the missing indicator and command.
+
+- [ ] **Step 3: Implement the quiet entry points**
+
+Place `HealthIndicator` in the right-side bar row before `ActivityIndicator`. It has no reserved width while hidden, no animation, and one compact shield/wrench glyph with an issue-count tooltip or accessible description. Use `Theme.warn` only for warnings and `Theme.danger` only for errors. Clicking calls `ShellState.openSettings("services")` and `Health.refresh()`.
+
+Add this dispatcher case and usage token:
+
+```bash
+health) qs ipc call health open ;;
+```
+
+Create a Vicinae script with schema version 1, silent mode, Panama Settings icon, keywords `health`, `doctor`, `repair`, `services`, and the stable `panama-action health` execution path.
+
+- [ ] **Step 4: Run focused tests**
+
+Run the three commands from Step 2.
+
+Expected: all PASS; command count increases from 17 to 18.
+
+- [ ] **Step 5: Commit the entry points**
+
+```bash
+git add config/dot/quickshell/modules/bar config/local/share/vicinae/scripts/check-system-health.sh config/dot/quickshell/scripts/panama-action tests/quickshell
+git commit -m "Add quiet System Health entry points"
+```
+
+### Task 6: Allow-listed repairs and observed recovery
+
+**Files:**
+- Modify: `config/dot/quickshell/scripts/panama-doctor`
+- Modify: `tests/quickshell/panama-doctor-contract.sh`
+- Modify: `config/dot/quickshell/services/Health.qml`
+- Modify: `tests/quickshell/health-service-contract.sh`
+- Modify: `config/dot/quickshell/modules/settings/HealthCheckRow.qml`
+- Modify: `tests/quickshell/health-ui-contract.sh`
+
+**Interfaces:**
+- Consumes: the fixed repair matrix in this plan and current accepted checks from `Health.qml`.
+- Produces: `panama-doctor --repair CHECK_ID --json` result `{schemaVersion, checkId, accepted, exitCode, message}`, inline repair state, and one post-repair scan.
+
+- [ ] **Step 1: Add exact repair-command tests**
+
+For every repair ID, use fake commands and isolated paths to assert the exact argv. Assert all of these are rejected before any process or filesystem write:
+
+```text
+unknown.check
+integration.home-assistant
+input.brightness
+desktop.notifications
+../../escape
+desktop.vicinae;touch injected
+```
+
+For runtime links, fixtures must prove only these link names are eligible: `hypr`, `quickshell`, `uwsm`, and `vicinae`; a regular user-owned directory is reported but never replaced. For Caffeine, only duplicate rows with application `Panama`, current UID, reason `Caffeine`, and mode `block` may yield numeric PIDs; leave one valid inhibitor alive and release extras.
+
+- [ ] **Step 2: Run repair contracts and verify failure**
+
+Run:
+
+```bash
+tests/quickshell/panama-doctor-contract.sh
+tests/quickshell/health-service-contract.sh
+```
+
+Expected: FAIL because `--repair` is not implemented.
+
+- [ ] **Step 3: Implement the authored repair registry**
+
+Represent commands as immutable constant tuples or dedicated functions:
+
+```python
+REPAIR_COMMANDS = {
+    "desktop.hyprpaper": ("systemctl", "--user", "restart", "hyprpaper.service"),
+    "desktop.hypridle": ("systemctl", "--user", "restart", "hypridle.service"),
+    "desktop.vicinae": ("systemctl", "--user", "restart", "vicinae.service"),
+    "desktop.quickshell": ("panama-action", "restart-shell"),
+}
+```
+
+Handle runtime links, Vicinae command linking, and duplicate inhibitors in dedicated functions that accept no caller-controlled path or command. Return JSON on every known failure. Unknown IDs exit 2 with `accepted: false` and do not invoke any runner.
+
+`Health.repair(id, external)` requires the ID to exist in the current snapshot with `action.kind === "repair"`, records `repairingId`, runs the helper with an argument array, parses the result, clears the busy row, and requests exactly one fresh scan. Keep the row degraded until that scan reports recovery.
+
+- [ ] **Step 4: Run repair and UI contracts**
+
+Run:
+
+```bash
+tests/quickshell/panama-doctor-contract.sh
+tests/quickshell/health-service-contract.sh
+tests/quickshell/health-ui-contract.sh
+```
+
+Expected: all PASS.
+
+- [ ] **Step 5: Commit repairs**
+
+```bash
+git add config/dot/quickshell/scripts/panama-doctor config/dot/quickshell/services/Health.qml config/dot/quickshell/modules/settings/HealthCheckRow.qml tests/quickshell
+git commit -m "Add bounded Panama recovery actions"
+```
+
+### Task 7: Full verification, controller-deferred live audit, and documentation
+
+**Integration note:** `origin/main` added Mouse, Privacy, Region, and Online
+Accounts destinations while this feature was in review. Merge commit `4ef2f01`
+preserves those routes and the newer Settings navigation architecture, keeps
+the stable `services` route rendered by `HealthPage`, and leaves
+`ServicesPage.qml` retired. Its useful Fedora handoffs for Users, Sharing,
+Colour profiles, and Digital wellbeing now live in the boundary-last System
+Health card alongside the existing network handoff, with focused static and
+isolated runtime coverage.
+
+**Live-audit handoff:** Per the integration brief, this task does not reload the
+daily-driver Quickshell, invoke a live repair, or run the read-only live
+doctor/IPC comparison. Those checks remain for the controller after code review.
+
+**Files:**
+- Modify: `config/dot/hypr/DESKTOP-PARITY.md`
+- Modify: `config/dot/quickshell/modules/settings/README.md`
+- Modify: `docs/superpowers/plans/2026-08-18-panama-health-recovery.md`
+
+**Interfaces:**
+- Consumes: the complete feature and existing regression suite.
+- Produces: current user documentation and final contract evidence. The
+  redacted live health snapshot and live shell audit are deferred to the
+  controller after code review.
+
+- [x] **Step 1: Document boundaries and entry points**
+
+Document `Panama: Check System Health`, Settings → System Health, the degraded-only bar indicator, `panama-doctor --summary`, the no-`sudo`/no-package-install boundary, and the fact that GNOME/Fedora tools remain responsible for generic system configuration.
+
+- [ ] **Step 2: Run syntax, focused, and full contracts**
+
+Run:
+
+```bash
+python3 -m py_compile config/dot/quickshell/scripts/panama-doctor
+bash -n config/dot/quickshell/scripts/panama-action
+tests/quickshell/panama-doctor-contract.sh
+tests/quickshell/health-service-contract.sh
+tests/quickshell/health-ui-contract.sh
+for test in tests/quickshell/*contract.sh; do "$test"; done
+for test in tests/hypr/*contract.sh; do "$test"; done
+```
+
+Expected: every command exits 0. After the latest Settings and installer work,
+the current inventory is 66 Quickshell contracts and 2 Hyprland contracts (the original
+pre-merge estimate was 58).
+
+Integration result: syntax and all focused Health/Settings contracts pass. Two
+complete serial Quickshell runs each passed 63/65, but failed on different
+order-sensitive contracts. Run one failed Displays and Settings Hyprland Write;
+run two failed Focus Session and Health Service. Each failed contract passed
+immediately when rerun alone. Hyprland contracts passed 2/2. No out-of-scope
+test or service code was changed to hide this suite-order interference.
+
+- [ ] **Step 3: Controller runs a redacted live read-only comparison**
+
+Deferred to the controller after code review; Task 7 does not produce this
+live output.
+
+Run:
+
+```bash
+config/dot/quickshell/scripts/panama-doctor --json >"$(mktemp)"
+config/dot/quickshell/scripts/panama-doctor --summary
+systemctl --user is-active hyprpaper.service hypridle.service vicinae.service pipewire.service
+qs ipc call health refresh
+qs ipc call health status | jq '{status, busy, checks: [.checks[] | {id, status}]}'
+```
+
+Expected: helper and direct service states agree. Do not print details from integrations; copied and IPC reports contain only redacted authored observations.
+
+- [ ] **Step 4: Controller reloads and inspects the live shell**
+
+Deferred to the controller after code review; Task 7 does not reload or inspect
+the daily-driver shell.
+
+Run:
+
+```bash
+qs reload
+sleep 4
+journalctl --user --since '-2 minutes' --no-pager | rg -i 'quickshell|qml|panama' | tail -200
+```
+
+Expected: the shell returns, System Health opens, the healthy state is silent, and there are no new QML errors or binding-loop warnings. Do not invoke a repair during this step.
+
+- [ ] **Step 5: Final diff and commit**
+
+Run:
+
+```bash
+git diff --check
+git status --short
+git diff --stat origin/main...HEAD
+git add config/dot/hypr/DESKTOP-PARITY.md config/dot/quickshell/modules/settings/README.md docs/superpowers/plans/2026-08-18-panama-health-recovery.md
+git commit -m "Document Panama health and recovery"
+```
+
+Expected: only intentional Health & Recovery files are present and no workstation-specific values appear in the diff.

docs/superpowers/specs/2026-08-18-panama-health-recovery-design.md

@@ -0,0 +1,235 @@
+# Panama Health & Recovery Design
+
+## Purpose
+
+Panama Health & Recovery makes the desktop explain itself. It verifies the
+local services, dependencies, links, and integrations that Panama relies on,
+then presents useful recovery actions without asking the user to read logs or
+diagnose a collection of unrelated Linux processes.
+
+The feature is intentionally quiet. A healthy desktop produces no notification,
+banner, or permanent bar ornament. Problems appear in Panama Settings and, when
+actionable, as one restrained bar indicator. User-initiated repairs receive
+immediate Prism OSD or inline feedback.
+
+## Product boundaries
+
+The first release covers Panama-owned or Panama-integrated functionality:
+
+- Hyprland, Quickshell, the notification server, XDG desktop portals, PipeWire,
+  Vicinae, the clipboard watcher, wallpaper, idle policy, and Panama's runtime
+  configuration links.
+- The Panama command collection, screenshot and OCR dependencies, DDC
+  brightness support, and the currently selected terminal and launcher.
+- Nextcloud, RustDesk, KDE Connect, BlueBubbles, Home Assistant, calendar
+  aggregation, and the configured autostart entries.
+- Orphaned Panama processes and inhibitors, including duplicate Caffeine locks.
+- Versions and non-sensitive diagnostic context needed for a useful copied
+  report.
+
+It does not become a package manager, a generic system monitor, or a replacement
+for Fedora's troubleshooting tools. It never installs packages, invokes `sudo`,
+deletes user data, rewrites arbitrary configuration, or repairs services Panama
+does not own.
+
+An optional integration that has never been configured is neutral **Not set
+up**, not a warning. A configured integration that cannot operate is degraded.
+This distinction prevents the health UI from pressuring the user to enable
+features they do not want.
+
+## Information architecture
+
+The existing **Startup & Services** destination becomes **System Health**. This
+avoids two pages reporting the same background services. Its existing Open and
+Refresh actions remain available through the richer health rows.
+
+The page has four levels:
+
+1. A compact summary hero: **Healthy**, **Needs attention**, or **Action
+   required**, the last completed scan time, Refresh, and Copy Report.
+2. An issues-first section shown only when one or more checks are degraded.
+3. Grouped cards for Desktop Foundation, Input & Media, Integrations, and Panama
+   Tools. Healthy rows remain visible but visually quiet.
+4. A short boundary note linking to GNOME or Fedora tools for system areas Panama
+   does not own.
+
+Each row contains a stable title, one-sentence observation, status label, and at
+most one primary action. Actions use concrete language such as **Restart
+Vicinae**, **Repair command link**, **Open Home settings**, or **View setup
+instructions**. There is no generic Fix Everything button.
+
+The Settings sidebar's existing health footer becomes real and clickable. It
+shows the aggregate state and opens System Health. The top bar gains a small
+`HealthIndicator` only while an actionable warning or error exists; clicking it
+opens the same page. Background scans never publish Signal Glass events or
+desktop notifications.
+
+## Diagnostic engine
+
+`config/dot/quickshell/scripts/panama-doctor` is the single operating-system
+boundary. It supports:
+
+- `panama-doctor --json` for a complete versioned snapshot.
+- `panama-doctor --summary` for a concise human-readable installer or terminal
+  result.
+- `panama-doctor --repair CHECK_ID --json` for an explicitly allow-listed repair.
+
+The helper emits one schema:
+
+```json
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-08-18T12:00:00Z",
+  "summary": {
+    "status": "warning",
+    "healthy": 18,
+    "warnings": 1,
+    "errors": 0,
+    "unconfigured": 2
+  },
+  "checks": [
+    {
+      "id": "launcher.panama-commands",
+      "group": "panama-tools",
+      "title": "Panama Commands",
+      "status": "warning",
+      "detail": "16 of 17 commands are loaded",
+      "action": {
+        "kind": "repair",
+        "label": "Repair command link"
+      }
+    }
+  ]
+}
+```
+
+Allowed statuses are `ok`, `warning`, `error`, and `unconfigured`. Check IDs,
+group IDs, titles, and repair mappings are authored constants. Probe output may
+populate observations but can never become a command or executable argument.
+
+Checks run concurrently where doing so is safe, with short per-probe timeouts.
+A failed or timed-out probe yields a check result rather than aborting the whole
+snapshot. Output order is deterministic so tests, copied reports, and visual
+rows do not jump between scans.
+
+No secrets are read. The report may state whether a Home Assistant URL or token
+is configured, but never includes either value. It excludes clipboard contents,
+notification bodies, calendar event data, SSIDs, device addresses, environment
+values, file contents, and command output that has not been explicitly parsed.
+
+## Quickshell state and refresh model
+
+`services/Health.qml` owns the latest accepted snapshot, aggregate severity,
+busy state, last scan time, and the result of the most recent repair. It invokes
+`panama-doctor` with argument arrays through `Process`; UI components never
+construct shell commands.
+
+Health performs one delayed scan after the shell reaches a stable startup state.
+It scans again when the System Health page is opened, when the user presses
+Refresh, and after a repair settles. There is no periodic polling loop while the
+desktop is idle. Services that already expose event-driven state remain the
+authoritative source for their own interactive controls; Health is a diagnostic
+snapshot, not a competing live service model.
+
+Every scan receives a monotonically increasing generation. Late output from an
+older scan is discarded. A malformed snapshot leaves the last valid result in
+place, marks the diagnostic engine unavailable, and offers a bounded Retry.
+
+The shell exposes a typed `health` IPC target with `refresh`, `status`, `open`,
+and `repair(id)` operations. Vicinae gains **Panama: Check System Health**, which
+opens the page and requests a fresh scan through the existing `panama-action`
+dispatcher.
+
+## Repair policy
+
+Repairs are narrow, reversible, and attached to one check. The first release may:
+
+- Restart Panama's user services such as Vicinae, Hyprpaper, or Hypridle.
+- Recreate Panama-owned symlinks when their destination is known and tracked.
+- Reload Vicinae's Panama command collection.
+- Release duplicate user-owned inhibitors whose metadata identifies Panama and
+  Caffeine.
+- Restart Quickshell through the verified `panama-action restart-shell` path.
+- Open the exact Panama Settings page required to finish credentials or entity
+  selection.
+
+Restarting a working service is not presented as a repair. Repairs that interrupt
+visible desktop chrome require a confirmation sheet in Settings. Navigation and
+setup actions do not. Package installation, privileged service changes, display
+mode writes, and destructive cleanup are never automatic; the UI shows concise
+instructions instead.
+
+After a repair, Health rescans and judges success from the observed result. A
+zero exit status alone never turns a row green. Failure remains inline on the
+affected row and also produces the existing Panama action-failure notification
+when the action originated outside Settings.
+
+## Visual language and interaction
+
+System Health uses the established Settings cards and Prism tokens. Healthy
+states use a small muted green dot and subdued **Healthy** copy. Warnings use
+amber; red is reserved for functionality that is configured, required, and
+currently broken. `unconfigured` rows use neutral gray.
+
+The summary hero does not use a decorative gauge, percentage score, pulse,
+shimmer, or animated gradient. A desktop is not “82% healthy.” The headline and
+issue count are more understandable and do not create false precision.
+
+Rows keep their height stable while refreshing. The previous snapshot remains
+visible with a quiet **Checking…** label rather than replacing the page with a
+spinner. Keyboard focus order reaches Refresh, Copy Report, issue rows, repair
+actions, and external handoffs. Status is always expressed in text as well as
+color.
+
+Before production components are edited, the page and degraded bar indicator
+will be shown in several static mocks using the existing Settings geometry. The
+chosen mock must preserve this information architecture and Panama's current
+Prism language rather than introduce a new visual system.
+
+## Failure handling
+
+- Missing required executables become actionable check results.
+- Missing optional applications remain neutral until configured.
+- A doctor crash, timeout, or malformed JSON does not clear the last good
+  snapshot or crash Quickshell.
+- Concurrent refresh requests coalesce into one follow-up scan.
+- A repair request for an unknown or non-repairable ID is rejected before any
+  process starts.
+- Copy Report uses only the already-redacted snapshot and reports clipboard
+  failure inline.
+- If the Settings window is closed during a scan or repair, the process may
+  finish; reopening the page shows the settled result.
+
+## Verification
+
+- Run the real helper against isolated fake command, config, state, and runtime
+  directories and prove every status transition deterministically.
+- Validate the JSON schema, stable check IDs, deterministic ordering, and
+  uniqueness of each ID.
+- Prove unconfigured integrations remain neutral while configured failures are
+  degraded.
+- Prove reports contain no fixture secrets, clipboard text, calendar data,
+  addresses, or unparsed environment values.
+- Exercise every repair through the allow-list, assert its exact command, and
+  prove unknown IDs cannot execute anything.
+- Test scan generations, malformed snapshots, refresh coalescing, repair
+  rescans, and preservation of the last valid state in a Quickshell harness.
+- Verify Settings routing, search entries, the live sidebar footer, and the
+  degraded-only bar indicator without QML warnings.
+- Validate the Vicinae command and typed IPC surface.
+- Run a read-only doctor scan on the real workstation and compare key results to
+  direct service checks. State-changing live repair tests require an actually
+  degraded disposable target or explicit user approval.
+- Restart the live shell, inspect the fresh log, and visually review healthy,
+  warning, error, unconfigured, refreshing, and repair-result states.
+
+## Delivery slices
+
+1. Diagnostic schema, read-only probes, redaction, and contract tests.
+2. `Health.qml`, typed IPC, startup/manual refresh, and fixture harness.
+3. System Health Settings page, live sidebar footer, search, and report copy.
+4. Degraded-only bar indicator and Vicinae command.
+5. Allow-listed repairs, confirmations, post-repair verification, and live audit.
+
+The slices are one feature and land together. Their order keeps the UI backed by
+real diagnostics from its first production render.

install

@@ -1,11 +1,24 @@
 #!/usr/bin/env bash
-source ~/.local/share/Panama/bin/ascii
+
-# Set host name
+# Panama's installer. Safe to re-run: every stage is idempotent, and this is
+# also the upgrade path.
+
+set -uo pipefail
+
+PANAMA_PATH="${PANAMA_PATH:-$HOME/.local/share/Panama}"
+source "$PANAMA_PATH/bin/ascii"
+
+# ── Hostname, which is optional ──────────────────────────────────────────────
+#
+# Declining this used to `exit`, which aborted the ENTIRE installation. The
+# prompt defaults to N, so simply pressing Enter -- the obvious thing to do when
+# you do not want to rename your machine -- installed nothing at all and said
+# nothing about it.
 echo -e "Current hostname is: $(hostname)"
-read -p "Do you want to change the hostname? [y/N]: " confirm_change
+read -r -p "Do you want to change the hostname? [y/N]: " confirm_change
 if [[ "$confirm_change" =~ ^[Yy]$ ]]; then
-  read -p "Hostname: " HOST_NAME
+  read -r -p "Hostname: " HOST_NAME
-  read -p "Set hostname to '$HOST_NAME'? [y/N]: " confirm_hostname
+  read -r -p "Set hostname to '$HOST_NAME'? [y/N]: " confirm_hostname
   if [[ "$confirm_hostname" =~ ^[Yy]$ ]]; then
     sudo hostnamectl set-hostname "$HOST_NAME"
     echo "Hostname set to: $(hostname)"
@@ -13,18 +26,45 @@ if [[ "$confirm_change" =~ ^[Yy]$ ]]; then
     echo "Hostname not changed."
   fi
 else
-  echo "Not changing hostname."
+  echo "Keeping the current hostname."
-  exit
 fi
 
-# Ensure computer doesn't go to sleep.
+# ── Keep the machine awake for the duration ──────────────────────────────────
-gsettings set org.gnome.desktop.screensaver lock-enabled false
+# Package installation takes long enough to hit an idle lock, and being locked
-gsettings set org.gnome.desktop.session idle-delay 0
+# out mid-transaction is unpleasant. Restored on every exit path, including
+# failure and Ctrl-C, so an interrupted install does not leave the screen
+# permanently awake.
+restore_idle() {
+  gsettings set org.gnome.desktop.screensaver lock-enabled true 2>/dev/null || true
+  gsettings set org.gnome.desktop.session idle-delay 300 2>/dev/null || true
+}
+trap restore_idle EXIT INT TERM
 
-# Run each setup stage in its own process. This keeps strict-shell options and
+gsettings set org.gnome.desktop.screensaver lock-enabled false 2>/dev/null || true
-# helper variables local to the script that owns them.
+gsettings set org.gnome.desktop.session idle-delay 0 2>/dev/null || true
-for script in ~/.local/share/Panama/setup/scripts/*; do "$script"; done
 
-# Revert to normal idle settings
+# ── Stages ───────────────────────────────────────────────────────────────────
-gsettings set org.gnome.desktop.screensaver lock-enabled true
+# Each runs in its own process so strict-shell options and helper variables stay
-gsettings set org.gnome.desktop.session idle-delay 300
+# local to the script that owns them. A failing stage is reported and the rest
+# still run: a missing optional package should not stop the dotfiles being
+# linked. The summary at the end is what decides whether the install worked,
+# because a failure scrolled past twenty minutes ago is a failure nobody saw.
+failed=()
+for script in "$PANAMA_PATH"/setup/scripts/*; do
+  [[ -x "$script" ]] || continue
+  stage="$(basename "$script")"
+  printf '\n=== %s ===\n' "$stage"
+  if ! "$script"; then
+    failed+=("$stage")
+    printf '!!! %s failed\n' "$stage" >&2
+  fi
+done
+
+printf '\n'
+if (( ${#failed[@]} == 0 )); then
+  echo "Panama installed. Log out and choose the Hyprland session to start it."
+else
+  printf 'Panama installed with %d failed stage(s): %s\n' "${#failed[@]}" "${failed[*]}" >&2
+  printf 'Re-running ./install is safe and will retry them.\n' >&2
+  exit 1
+fi

setup/packages/hyprland-packages

@@ -1,38 +1,45 @@
-hyprland
+NetworkManager
-hyprland-uwsm
-uwsm
-quickshell
-vicinae
-hyprlock
-hypridle
-hyprpaper
-hyprpicker
-hyprsunset
-hyprpolkitagent
-hyprshutdown
-hyprpwcenter
-hyprsysteminfo
-hyprland-guiutils
-xdg-desktop-portal-hyprland
-grim
-slurp
-grimblast
-satty
-wl-clipboard
-wf-recorder
-gpu-screen-recorder
-brightnessctl
-playerctl
-pamixer
-udiskie
-wofi
 adw-gtk3-theme
 adwaita-icon-theme
 adwaita-sans-fonts
-qt6-qtwayland
+brightnessctl
-nm-connection-editor
+ddcutil
+gpu-screen-recorder
+grim
+grimblast
+gtk-update-icon-cache
+hypridle
+hyprland
+hyprland-guiutils
+hyprland-uwsm
+hyprlock
+hyprpaper
+hyprpicker
+hyprpolkitagent
+hyprpwcenter
+hyprshutdown
+hyprsunset
+hyprsysteminfo
 kde-connect
+libnotify
+nm-connection-editor
+orca
+pamixer
+playerctl
+qrencode
+qt6-qtwayland
+quickshell
+satty
+slurp
+system-config-printer
 tesseract
 tesseract-langpack-eng
+udiskie
+uwsm
+vicinae
+wf-recorder
+wireplumber
+wl-clipboard
+wofi
+xdg-desktop-portal-hyprland
 zbar
-system-config-printer

setup/packages/initial-packages

@@ -1,18 +1,27 @@
 awk
 bat
+btop
 cargo
 curl
 eza
+fontconfig
+fwupd
 fzf
-git-all
 gh
+git-all
 gum
+jq
+kitty
 ksshaskpass
+libselinux-utils
 neovim
 openssl
+pciutils
+python3-dnf
 python3-neovim
 rustup
+tmux
 unzip
-wireguard-tools
 wget
+wireguard-tools
 zoxide

setup/scripts/link-dotfiles

@@ -70,6 +70,45 @@ for dir in "${dirs[@]}"; do
   log "Linked $PANAMA_DOT/$dir → $CONFIG/$dir"
 done
 
+# tmux.conf ends with a source-file of current-theme.conf, generated from the
+# colour scheme rather than committed. Seed it so a fresh checkout starts themed
+# -- the source-file is -q, so a missing file is silent, which would leave tmux
+# unstyled with nothing to explain it.
+TMUX_THEME="$PANAMA_DOT/tmux/current-theme.conf"
+if [ -e "$TMUX_THEME" ]; then
+  log "Keeping existing tmux theme at $TMUX_THEME"
+elif [ -d "$PANAMA_DOT/tmux/themes" ]; then
+  tmux_scheme="dark"
+  tmux_prefs="${XDG_CONFIG_HOME:-$HOME/.config}/panama/settings.json"
+  if [ -r "$tmux_prefs" ]; then
+    tmux_stored="$(jq -r '.colorScheme // "dark"' "$tmux_prefs" 2>/dev/null || echo dark)"
+    [ "$tmux_stored" = "light" ] && tmux_scheme="light"
+  fi
+  [ "$tmux_scheme" = "light" ] && tmux_name="tokyonight-day" || tmux_name="tokyonight-moon"
+  cp "$PANAMA_DOT/tmux/themes/$tmux_name.conf" "$TMUX_THEME"
+  log "Seeded tmux $tmux_scheme theme ($tmux_name) → $TMUX_THEME"
+fi
+
+# btop reads themes from its own config directory, but OWNS btop.conf -- it
+# rewrites that file on exit -- so only the theme files are exposed, per file,
+# and the config itself is left to btop. panama-theme-apps edits the single
+# color_theme line in place.
+BTOP_THEME_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/btop/themes"
+mkdir -p "$BTOP_THEME_DIR"
+for btop_theme_src in "$PANAMA_DOT"/btop/themes/*.theme; do
+  [ -e "$btop_theme_src" ] || continue
+  btop_theme_dst="$BTOP_THEME_DIR/$(basename "$btop_theme_src")"
+  if [ -L "$btop_theme_dst" ]; then
+    rm "$btop_theme_dst"
+  fi
+  if [ -e "$btop_theme_dst" ]; then
+    log "Keeping existing btop theme at $btop_theme_dst"
+  else
+    ln -s "$btop_theme_src" "$btop_theme_dst"
+    log "Linked btop theme → $btop_theme_dst"
+  fi
+done
+
 # GTK3 has no include mechanism, so its settings.ini is generated whole from a
 # template rather than layered. Without this, a fresh checkout has a template
 # and no settings.ini, and GTK3 applications fall back to their built-in theme.

tests/quickshell/declared-dependencies-contract.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+
+# Every external command Panama's own scripts invoke must be installed by
+# Panama's own package lists.
+#
+# This exists because the lists had drifted badly. jq is used by thirty-one call
+# sites across the helpers and the contracts; kitty has a full shipped config
+# and a dock pin; tmux and btop have shipped themes that the colour scheme
+# switches. None of the four were declared. So a fresh machine that followed
+# this repository's own install instructions would not have them.
+#
+# The failure is quiet by design, which is what makes it worth a test: the
+# helpers are written to report "not installed" rather than crash, so a missing
+# dependency presents as a feature that silently is not there.
+#
+# Commands from coreutils and the shell itself are not checked -- nothing
+# installs those separately, and listing them would be noise.
+
+set -uo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+fail() {
+    printf 'declared dependencies contract: %s\n' "$1" >&2
+    exit 1
+}
+
+# Shell syntax and builtins. These are not commands anyone installs, and the
+# first version of this contract reported `then`, `esac` and `done` as missing
+# packages, which buried the four real findings in a hundred lines of noise.
+SHELL_WORDS='^(if|then|else|elif|fi|for|while|until|do|done|case|esac|in|function|select|time|coproc|break|continue|return|exit|local|readonly|declare|export|unset|shift|eval|exec|source|trap|set|shopt|alias|unalias|builtin|command|enable|help|let|read|mapfile|printf|echo|test|true|false|wait|jobs|bg|fg|kill|pwd|cd|dirs|pushd|popd|umask|type|hash|getopts|split|sync)$'
+
+# Provided by any Fedora install: coreutils, util-linux, the shell, and the
+# systemd/session tooling. Nothing here is a choice Panama makes.
+BASELINE='^(sh|bash|cat|cut|sed|awk|gawk|grep|egrep|head|tail|sort|uniq|tr|wc|find|xargs|basename|dirname|mkdir|rm|cp|mv|ln|chmod|chown|stat|df|du|date|sleep|env|id|tee|touch|mktemp|readlink|realpath|seq|comm|join|paste|od|file|nl|fold|column|tput|timeout|flock|install|sha256sum|md5sum|base64|nproc|uptime|free|uname|hostname|whoami|ps|pgrep|pkill|kill|killall|lsblk|mount|umount|sudo|su|rpm|dnf|flatpak|git|python3|ss|ip|lsof)$'
+
+SESSION='^(systemctl|busctl|journalctl|loginctl|hostnamectl|localectl|systemd-inhibit|systemd-run|udevadm|gsettings|dconf|dbus-send|dbus-monitor|hyprctl|qs|quickshell|gnf|panama|wl-copy|wl-paste)$'
+
+declared="$(cat "$repo_dir"/setup/packages/* 2>/dev/null | sed 's/#.*//' | tr -d ' ' | grep -v '^$' | sort -u)"
+[[ -n "$declared" ]] || fail 'no package lists found'
+
+# A package is not always named after its command. Only the genuine mismatches
+# are mapped, so an unmapped command is a real omission rather than a lookup
+# failure.
+package_for() {
+    case "$1" in
+        zbarimg)        printf 'zbar' ;;
+        fc-list|fc-match) printf 'fontconfig' ;;
+        lspci)          printf 'pciutils' ;;
+        getenforce)     printf 'libselinux-utils' ;;
+        nmcli)          printf 'NetworkManager' ;;
+        wpctl)          printf 'wireplumber' ;;
+        nvim)           printf 'neovim' ;;
+        fwupdmgr)       printf 'fwupd' ;;
+        dnf4)           printf 'python3-dnf' ;;
+        notify-send)    printf 'libnotify' ;;
+        wl-copy|wl-paste) printf 'wl-clipboard' ;;
+        rg)             printf 'ripgrep' ;;
+        python3)        printf 'python3' ;;
+        *)              printf '%s' "$1" ;;
+    esac
+}
+
+missing=()
+checked=0
+
+while read -r script; do
+    [[ -n "$script" ]] || continue
+    head -1 "$script" | grep -qE 'bash|/sh' || continue
+
+    # Commands appearing at the start of a statement or after a pipe. Crude, but
+    # it is looking for undeclared dependencies, not building a call graph.
+    #
+    # No minimum length. An earlier version required three characters, which
+    # quietly excluded the most-used dependency in the repository -- jq, at
+    # thirty-one call sites -- along with rg, ss and ip. A dependency checker
+    # with a blind spot for short names is worse than none, because it reports
+    # PASS.
+    while read -r cmd; do
+        [[ -n "$cmd" ]] || continue
+        [[ "$cmd" =~ $SHELL_WORDS ]] && continue
+        [[ "$cmd" =~ $BASELINE ]] && continue
+        [[ "$cmd" =~ $SESSION ]] && continue
+
+        pkg="$(package_for "$cmd")"
+        grep -qx "$pkg" <<<"$declared" && continue
+
+        # Only report a command that actually exists on this machine. An
+        # invented name in a comment or a heredoc is a false positive; a real
+        # binary that nothing declares is the thing being looked for.
+        command -v "$cmd" >/dev/null 2>&1 || continue
+
+        missing+=("$cmd (from $(basename "$script"), package: $pkg)")
+    done < <({
+        # Statement-initial or after a pipe.
+        grep -oE '(^|[|;&]|\$\()[[:space:]]*[a-z][a-z0-9_-]+' "$script" \
+            | grep -oE '[a-z][a-z0-9_-]+$'
+
+        # Behind a wrapper. ddcutil is always invoked as `timeout 10 ddcutil`,
+        # so it never appears statement-initial and was missed entirely.
+        grep -oE '\b(timeout[[:space:]]+[0-9.]+|sudo|nohup|env)[[:space:]]+[a-z][a-z0-9_-]+' "$script" \
+            | grep -oE '[a-z][a-z0-9_-]+$'
+
+        # `command -v X` is how these helpers probe for a tool before using it,
+        # which makes it the clearest possible statement of a dependency.
+        grep -oE 'command -v[[:space:]]+[a-z][a-z0-9_-]+' "$script" \
+            | grep -oE '[a-z][a-z0-9_-]+$'
+    } | sort -u)
+
+    checked=$((checked + 1))
+done < <(find "$repo_dir/config/dot/quickshell/scripts" \
+              "$repo_dir/config/local/share/vicinae/scripts" \
+              "$repo_dir/setup/scripts" "$repo_dir/bin" \
+              -type f 2>/dev/null)
+
+if (( ${#missing[@]} > 0 )); then
+    printf 'declared dependencies contract: commands used but never installed:\n' >&2
+    printf '  %s\n' "${missing[@]}" | sort -u >&2
+    fail 'add each to a list in setup/packages/, or the feature silently will not exist on a fresh machine'
+fi
+
+printf 'declared dependencies contract: PASS (%d scripts)\n' "$checked"

tests/quickshell/enum-hypr-map-contract.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+
+# Every enum backed by a Hyprland option must offer values that option accepts.
+#
+# This exists because of a bug that shipped: followMouse offered 0/1/2 labelled
+# "Never" / "Click to focus" / "Sloppy focus", while Hyprland's actual mapping
+# is disabled=0, follow=1, detached=2, separate=3. The desktop was labelled
+# "Click to focus" and was in fact following the pointer, the way to GET click
+# to focus was to choose "Never", and value 3 did not exist in the UI at all.
+#
+# Nothing detects that. The compositor accepts 1, reads back 1, and verification
+# passes -- the value is valid, it just means something else entirely. The only
+# authority on what each number MEANS is the compositor, which publishes it:
+#
+#   hyprctl descriptions -> { "name": "input:follow_mouse",
+#                             "map": [{"separate":3},{"detached":2},...] }
+#
+# So this checks the schema's enum values against that map, and against the
+# min/max range for mapped options that have no named map.
+
+set -uo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+schema="$repo_dir/config/dot/quickshell/config/PreferenceSchema.qml"
+
+fail() {
+    printf 'enum hypr map contract: %s\n' "$1" >&2
+    exit 1
+}
+
+command -v hyprctl >/dev/null 2>&1 || { printf 'enum hypr map contract: SKIP (no compositor)\n'; exit 0; }
+descriptions="$(hyprctl descriptions 2>/dev/null)" || fail 'could not read hyprctl descriptions'
+jq -e 'type == "array" and length > 0' >/dev/null <<<"$descriptions" \
+    || fail 'hyprctl descriptions did not return a list'
+
+# Pull every enum entry that carries a hypr option, as: key<TAB>option<TAB>values
+entries="$(python3 - "$schema" <<'PY'
+import re, sys
+
+text = open(sys.argv[1]).read()
+# Each schema entry is a brace-delimited block starting with `key:`.
+for block in re.findall(r'\{\s*\n?\s*key:\s*"([^"]+)"(.*?)\n        \}', text, re.S):
+    name, body = block
+    if 'type: "enum"' not in body:
+        continue
+    option = re.search(r'option:\s*"([^"]+)"', body)
+    if not option:
+        continue
+    values = re.findall(r'value:\s*(-?\d+)', body)
+    if not values:
+        continue
+    print(f"{name}\t{option.group(1)}\t{','.join(values)}")
+PY
+)"
+
+[[ -n "$entries" ]] || fail 'found no compositor-backed enums in the schema -- this contract is not reading it correctly'
+
+checked=0
+while IFS=$'\t' read -r key option values; do
+    [[ -n "$key" ]] || continue
+
+    entry="$(jq -c --arg name "$option" '.[] | select(.name == $name)' <<<"$descriptions")"
+    [[ -n "$entry" ]] || fail "$key maps to \"$option\", which the compositor does not publish"
+
+    map_values="$(jq -r 'if .map then (.map | map(to_entries[].value) | join(",")) else "" end' <<<"$entry")"
+
+    IFS=',' read -ra wanted <<<"$values"
+    for value in "${wanted[@]}"; do
+        if [[ -n "$map_values" ]]; then
+            grep -qx "$value" <<<"$(tr ',' '\n' <<<"$map_values")" \
+                || fail "$key offers $value for $option, which the compositor's map does not contain (it publishes: $map_values). A value outside the map is accepted and read back unchanged, so nothing else notices -- it simply means something other than the label says."
+        else
+            min="$(jq -r '.min // empty' <<<"$entry")"
+            max="$(jq -r '.max // empty' <<<"$entry")"
+            if [[ -n "$min" && -n "$max" ]]; then
+                (( value >= min && value <= max )) \
+                    || fail "$key offers $value for $option, outside the compositor's range $min..$max"
+            fi
+        fi
+    done
+
+    # Every value the compositor names should be offered. A missing one is a
+    # capability the user simply cannot reach -- value 3 was missing here.
+    if [[ -n "$map_values" ]]; then
+        while read -r published; do
+            [[ -n "$published" ]] || continue
+            grep -qx "$published" <<<"$(tr ',' '\n' <<<"$values")" \
+                || fail "$option publishes value $published but $key does not offer it, so that behaviour is unreachable from Settings"
+        done <<<"$(tr ',' '\n' <<<"$map_values")"
+    fi
+
+    checked=$((checked + 1))
+done <<<"$entries"
+
+printf 'enum hypr map contract: PASS (%d mapped enums)\n' "$checked"

tests/quickshell/fixtures/doctor/bin/busctl

@@ -0,0 +1,15 @@
+#!/usr/bin/bash
+
+set -euo pipefail
+
+if [[ "${PANAMA_DOCTOR_FIXTURE_BUS:-ready}" == "missing" ]]; then
+    exit 1
+fi
+if [[ "${PANAMA_DOCTOR_FIXTURE_BUS:-ready}" == "invalid-utf8" ]]; then
+    printf '\377\n'
+    exit 0
+fi
+printf '%s\n' \
+    'org.freedesktop.portal.Desktop 1000 portal' \
+    'org.kde.kdeconnect 1000 kdeconnect' \
+    'fixture clipboard body AA:BB:CC:DD:EE:FF'

tests/quickshell/fixtures/doctor/bin/pgrep

@@ -0,0 +1,11 @@
+#!/usr/bin/bash
+
+set -euo pipefail
+
+name="${!#}"
+case ",${PANAMA_DOCTOR_FIXTURE_PROCESSES:-}," in
+    *",$name:duplicate,"*) printf '4101\n4102\n' ;;
+    *",$name:malformed,"*) printf 'not-a-pid\n' ;;
+    *",$name:missing,"*) exit 1 ;;
+    *) printf '4101\n' ;;
+esac

tests/quickshell/fixtures/doctor/bin/qs

@@ -0,0 +1,15 @@
+#!/usr/bin/bash
+
+set -euo pipefail
+
+case "${1:-}" in
+    --version) printf '%s\n' "${PANAMA_DOCTOR_FIXTURE_QS_VERSION:-Quickshell 0.2.0}" ;;
+    ipc)
+        if [[ "${PANAMA_DOCTOR_FIXTURE_QS:-ready}" == "malformed" ]]; then
+            printf 'fixture-secret-token AA:BB:CC:DD:EE:FF\n'
+        else
+            printf '%s\n' 'target notifications' 'target clipboard' 'target wallpaper' 'target capture'
+        fi
+        ;;
+    *) exit 2 ;;
+esac

tests/quickshell/fixtures/doctor/bin/systemctl

@@ -0,0 +1,13 @@
+#!/usr/bin/bash
+
+set -euo pipefail
+
+if [[ -n ${PANAMA_DOCTOR_FIXTURE_PROBE_SECRET+x} ]]; then
+    exit 97
+fi
+
+service="${4:-}"
+case ",${PANAMA_DOCTOR_FIXTURE_STOPPED:-}," in
+    *",$service,"*) exit 3 ;;
+esac
+printf 'fixture-secret-token\n'

tests/quickshell/fixtures/doctor/bin/systemd-inhibit

@@ -0,0 +1,13 @@
+#!/usr/bin/bash
+
+set -euo pipefail
+
+uid="$(/usr/bin/id -u)"
+printf 'Panama %s fixture-user 4101 systemd-inhibit sleep:idle Caffeine block\n' "$uid"
+if [[ "${PANAMA_DOCTOR_FIXTURE_CAFFEINE:-single}" == "duplicate" ]]; then
+    printf 'Panama %s fixture-user 4102 systemd-inhibit sleep:idle Caffeine block\n' "$uid"
+fi
+if [[ "${PANAMA_DOCTOR_FIXTURE_CAFFEINE:-single}" == "malformed" ]]; then
+    printf 'Panama %s fixture-user invalid Caffeine\n' "$uid"
+fi
+printf 'Other %s fixture-secret-token AA:BB:CC:DD:EE:FF fixture clipboard body ignore ignore\n' "$uid"

tests/quickshell/fixtures/doctor/bin/vicinae

@@ -0,0 +1,9 @@
+#!/usr/bin/bash
+
+set -euo pipefail
+
+case "${1:-}" in
+    --version) printf 'Vicinae 0.26.0 fixture-secret-token\n' ;;
+    ping) exit 0 ;;
+    *) exit 2 ;;
+esac

tests/quickshell/health-service-contract.sh

@@ -0,0 +1,410 @@
+#!/usr/bin/env bash
+
+# Health owns the accepted diagnostic snapshot. A newer unreadable response
+# must degrade diagnostics without discarding the last report that Settings
+# and future health surfaces will render.
+
+set -euo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source_harness="$repo_dir/config/dot/quickshell/health-harness.qml"
+service="$repo_dir/config/dot/quickshell/services/Health.qml"
+shell="$repo_dir/config/dot/quickshell/shell.qml"
+warning_snapshot='{"schemaVersion":1,"generatedAt":"2026-08-18T00:00:00Z","summary":{"status":"warning","healthy":0,"warnings":2,"errors":0,"unconfigured":0},"context":{"session":"hyprland","versions":[{"id":"quickshell","version":"0.3.0"}]},"checks":[{"id":"integration.calendar","group":"integrations","title":"Calendar","status":"warning","detail":"Calendar probe timed out.","action":{"kind":"open","label":"Open Date & Time","confirm":false,"target":"datetime"}},{"id":"panama.caffeine","group":"panama-tools","title":"Caffeine","status":"warning","detail":"Duplicate inhibitors are active.","action":{"kind":"repair","label":"Release duplicate inhibitors","confirm":false}}]}'
+confirm_snapshot="$(jq -c '
+    .summary.status = "error"
+    | .summary.errors = 1
+    | .checks += [{
+        id: "desktop.quickshell",
+        group: "desktop-foundation",
+        title: "Quickshell",
+        status: "error",
+        detail: "Panama shell needs to restart.",
+        action: {kind: "repair", label: "Restart Panama", confirm: true}
+    }]
+' <<<"$warning_snapshot")"
+projection_snapshot="$(jq -c '
+    .fixtureSecret = "fixture-secret"
+    | .summary.fixtureSecret = "fixture-secret"
+    | .context.fixtureSecret = "fixture-secret"
+    | .context.versions[0].fixtureSecret = "fixture-secret"
+    | .checks[0].fixtureSecret = "fixture-secret"
+' <<<"$warning_snapshot")"
+adversarial_snapshot="$(jq -c '
+    .fixtureSecret = "fixture-secret"
+    | .summary.fixtureSecret = "fixture-secret"
+    | .context.fixtureSecret = "fixture-secret"
+    | .context.versions[0].fixtureSecret = "fixture-secret"
+    | .checks[0].fixtureSecret = "fixture-secret"
+    | .checks[0].action.fixtureSecret = "fixture-secret"
+' <<<"$warning_snapshot")"
+
+fail() {
+    printf 'health service contract: %s\n' "$1" >&2
+    exit 1
+}
+
+[[ -f "$service" ]] || fail 'Health.qml is missing'
+[[ -f "$source_harness" ]] || fail 'health harness is missing'
+[[ -f "$shell" ]] || fail 'shell.qml is missing'
+
+# shell.qml is not started here: it is the active desktop shell. Keep this
+# contract static while pinning the typed, redacted IPC boundary it exports.
+python3 - "$shell" <<'PY' || fail 'health IPC contract is missing or exposes unsafe state'
+import re
+import sys
+
+text = open(sys.argv[1], encoding="utf-8").read()
+match = re.search(r'IpcHandler \{\s*target: "health"(?P<body>.*?)\n    \}', text, re.S)
+if not match:
+    raise SystemExit(1)
+body = match.group("body")
+required = (
+    'function refresh(): bool { return Health.refresh(); }',
+    'function status(): string {',
+    'summary: Health.summary,',
+    'busy: Health.busy,',
+    'generation: Health.generation,',
+    'acceptedGeneration: Health.acceptedGeneration,',
+    'checks: Health.checks.map(check => ({ id: check.id, status: check.status }))',
+    'ShellState.openSettings("services");',
+    'Health.refresh();',
+    'function repair(id: string): bool { return Health.repair(id, true); }',
+)
+if any(entry not in body for entry in required):
+    raise SystemExit(1)
+if 'Health.snapshot' in body or 'Health.diagnostics' in body:
+    raise SystemExit(1)
+status = re.search(r'function status\(\): string \{\s*return JSON\.stringify\(\{(?P<fields>.*?)\n            \}\);', body, re.S)
+if not status:
+    raise SystemExit(1)
+keys = re.findall(r'^\s*([A-Za-z][A-Za-z0-9]*):', status.group("fields"), re.M)
+if keys != ["summary", "busy", "generation", "acceptedGeneration", "checks"]:
+    raise SystemExit(1)
+PY
+
+fixture_dir="$(mktemp -d /tmp/panama-health.XXXXXX)"
+config_path="$fixture_dir/quickshell"
+cp -a "$repo_dir/config/dot/quickshell" "$config_path"
+harness="$config_path/health-harness.qml"
+python3 - "$harness" <<'PY'
+import sys
+
+path = sys.argv[1]
+source = open(path, encoding="utf-8").read()
+needle = '        function repair(id: string): bool { return Health.repair(id, false); }\n'
+replacement = needle + '''        function externalRepair(id: string): bool { return Health.repair(id, true); }
+        function pendingRefreshRace(): string {
+            const before = Health.generation;
+            Health.finishRepair(0, "panama.caffeine", false, JSON.stringify({
+                schemaVersion: 1,
+                checkId: "panama.caffeine",
+                accepted: true,
+                exitCode: 0,
+                message: "Fixture repair completed."
+            }));
+            const accepted = Health.refresh();
+            return JSON.stringify({ accepted: accepted, before: before });
+        }
+'''
+if needle not in source:
+    raise SystemExit("health harness repair seam is missing")
+open(path, "w", encoding="utf-8").write(source.replace(needle, replacement))
+PY
+helper="$fixture_dir/panama-doctor"
+copy_bin="$fixture_dir/bin"
+copy_file="$fixture_dir/copied-report.json"
+repair_mode_file="$fixture_dir/repair-mode"
+repair_log="$fixture_dir/repair.log"
+notification_log="$fixture_dir/notifications.log"
+repair_started_file="$fixture_dir/repair-started"
+repair_release_file="$fixture_dir/repair-release"
+printf 'success\n' >"$repair_mode_file"
+printf '%s\n' \
+    '#!/usr/bin/env bash' \
+    'printf "%s\n" "$*" >>"$PANAMA_HEALTH_REPAIR_LOG"' \
+    'if [[ "$1" == "--json" ]]; then' \
+    '    sleep 0.2' \
+    "    printf '%s\\n' '$warning_snapshot'" \
+    '    exit 0' \
+    'fi' \
+    'if [[ "$1" == "--repair" ]]; then' \
+    '    repair_start_time="$(awk '\''{ print $22 }'\'' "/proc/$$/stat")"' \
+    '    printf "%s|%s\n" "$$" "$repair_start_time" >"$PANAMA_HEALTH_REPAIR_STARTED"' \
+    '    while [[ ! -e "$PANAMA_HEALTH_REPAIR_RELEASE" ]]; do sleep 0.02; done' \
+    'fi' \
+    'if [[ "$1" == "--repair" && "$2" == "panama.caffeine" && "$3" == "--json" ]]; then' \
+    '    case "$(cat "$PANAMA_HEALTH_REPAIR_MODE_FILE")" in' \
+    '        success) printf "{\"schemaVersion\":1,\"checkId\":\"panama.caffeine\",\"accepted\":true,\"exitCode\":0,\"message\":\"Duplicate inhibitors were released.\"}\\n"; exit 0 ;;' \
+    '        failed) printf "{\"schemaVersion\":1,\"checkId\":\"panama.caffeine\",\"accepted\":true,\"exitCode\":7,\"message\":\"Duplicate inhibitors could not be released.\"}\\n"; exit 7 ;;' \
+    '        mismatch) printf "{\"schemaVersion\":1,\"checkId\":\"desktop.vicinae\",\"accepted\":true,\"exitCode\":0,\"message\":\"Wrong row.\"}\\n"; exit 0 ;;' \
+    '        *) printf "not-json\\n"; exit 0 ;;' \
+    '    esac' \
+    'fi' \
+    'if [[ "$1" == "--repair" && "$2" == "desktop.quickshell" && "$3" == "--json" ]]; then' \
+    '    printf "{\"schemaVersion\":1,\"checkId\":\"desktop.quickshell\",\"accepted\":true,\"exitCode\":0,\"message\":\"Panama shell restart was requested.\"}\\n"' \
+    '    exit 0' \
+    'fi' \
+    'exit 2' >"$helper"
+chmod +x "$helper"
+mkdir -p "$copy_bin"
+printf '%s\n' \
+    '#!/usr/bin/env bash' \
+    '/usr/bin/cat > "$PANAMA_HEALTH_COPY_FILE"' >"$copy_bin/wl-copy"
+printf '%s\n' \
+    '#!/usr/bin/env bash' \
+    'printf "%s\n" "$*" >>"$PANAMA_HEALTH_NOTIFICATION_LOG"' >"$copy_bin/notify-send"
+chmod +x "$copy_bin/wl-copy" "$copy_bin/notify-send"
+
+run() {
+    PATH="$copy_bin:$PATH" PANAMA_HEALTH_HELPER="$helper" PANAMA_HEALTH_COPY_FILE="$copy_file" \
+    PANAMA_HEALTH_REPAIR_MODE_FILE="$repair_mode_file" PANAMA_HEALTH_REPAIR_LOG="$repair_log" \
+    PANAMA_HEALTH_NOTIFICATION_LOG="$notification_log" \
+    PANAMA_HEALTH_REPAIR_STARTED="$repair_started_file" PANAMA_HEALTH_REPAIR_RELEASE="$repair_release_file" \
+    qs -p "$harness" "$@"
+}
+harness_pid=""
+harness_start_time=""
+
+process_identity_matches() {
+    local pid="$1" expected_start_time="$2" expected_command="${3:-}" current_start_time
+
+    [[ "$pid" =~ ^[0-9]+$ && "$expected_start_time" =~ ^[0-9]+$ ]] || return 1
+    [[ -r "/proc/$pid/stat" ]] || return 1
+    current_start_time="$(awk '{ print $22 }' "/proc/$pid/stat" 2>/dev/null)" || return 1
+    [[ "$current_start_time" == "$expected_start_time" ]] || return 1
+    if [[ -n "$expected_command" ]]; then
+        [[ -r "/proc/$pid/cmdline" ]] || return 1
+        tr '\0' '\n' <"/proc/$pid/cmdline" | grep -Fxq "$expected_command"
+    fi
+}
+
+cleanup() {
+    : >"$repair_release_file"
+    if [[ -f "$repair_started_file" ]]; then
+        IFS='|' read -r repair_pid repair_start_time <"$repair_started_file" || true
+        if process_identity_matches "$repair_pid" "$repair_start_time" "$helper"; then
+            for _ in $(seq 1 40); do
+                ! process_identity_matches "$repair_pid" "$repair_start_time" "$helper" && break
+                sleep 0.05
+            done
+            if process_identity_matches "$repair_pid" "$repair_start_time" "$helper"; then
+                kill "$repair_pid" >/dev/null 2>&1 || true
+                for _ in $(seq 1 20); do
+                    ! process_identity_matches "$repair_pid" "$repair_start_time" "$helper" && break
+                    sleep 0.05
+                done
+                if process_identity_matches "$repair_pid" "$repair_start_time" "$helper"; then
+                    kill -KILL "$repair_pid" >/dev/null 2>&1 || true
+                fi
+            fi
+        fi
+    fi
+    if process_identity_matches "$harness_pid" "$harness_start_time"; then
+        kill "$harness_pid" >/dev/null 2>&1 || true
+        for _ in $(seq 1 40); do
+            ! process_identity_matches "$harness_pid" "$harness_start_time" && break
+            sleep 0.05
+        done
+        if process_identity_matches "$harness_pid" "$harness_start_time"; then
+            kill -KILL "$harness_pid" >/dev/null 2>&1 || true
+        fi
+    fi
+    rm -rf "$fixture_dir"
+}
+trap cleanup EXIT
+
+PATH="$copy_bin:$PATH" PANAMA_HEALTH_HELPER="$helper" PANAMA_HEALTH_COPY_FILE="$copy_file" \
+    PANAMA_HEALTH_REPAIR_MODE_FILE="$repair_mode_file" PANAMA_HEALTH_REPAIR_LOG="$repair_log" \
+    PANAMA_HEALTH_NOTIFICATION_LOG="$notification_log" \
+    PANAMA_HEALTH_REPAIR_STARTED="$repair_started_file" PANAMA_HEALTH_REPAIR_RELEASE="$repair_release_file" \
+    qs -p "$harness" --daemonize >/dev/null
+for _ in $(seq 1 40); do
+    run ipc show 2>/dev/null | rg -q '^target health-test$' && break
+    sleep 0.1
+done
+run ipc show 2>/dev/null | rg -q '^target health-test$' || fail 'test IPC target did not start'
+harness_pid="$(run list | awk '/Process ID:/ { print $3; exit }')"
+harness_start_time="$(awk '{ print $22 }' "/proc/$harness_pid/stat" 2>/dev/null || true)"
+process_identity_matches "$harness_pid" "$harness_start_time" \
+    || fail 'could not capture a stable health harness process identity'
+
+[[ "$(run ipc call health-test accept "$warning_snapshot" 0)" == "true" ]] \
+    || fail 'valid warning snapshot was rejected'
+state="$(run ipc call health-test status)"
+jq -e '.status == "warning" and .acceptedGeneration == 0 and .checks == ["integration.calendar", "panama.caffeine"] and .diagnosticUnavailable == false' \
+    >/dev/null <<<"$state" || fail "valid warning snapshot was not accepted intact: $state"
+
+[[ "$(run ipc call health-test accept "$projection_snapshot" 0)" == "true" ]] \
+    || fail 'snapshot with unknown non-action fields was rejected instead of safely projected'
+stored_report="$(run ipc call health-test report)"
+! grep -Fq 'fixture-secret' <<<"$stored_report" \
+    || fail "accepted snapshot retained an unknown secret field: $stored_report"
+[[ "$(run ipc call health-test copy)" == "true" ]] \
+    || fail 'copy report was refused'
+for _ in $(seq 1 40); do
+    [[ -f "$copy_file" ]] && break
+    sleep 0.1
+done
+[[ -f "$copy_file" ]] || fail 'copy report did not reach wl-copy'
+! grep -Fq 'fixture-secret' "$copy_file" \
+    || fail 'copied report retained an unknown secret field'
+
+adversarial_result="$(run ipc call health-test accept "$adversarial_snapshot" 1)"
+[[ "$adversarial_result" == "true" || "$adversarial_result" == "false" ]] \
+    || fail "adversarial action fixture did not return a Boolean: $adversarial_result"
+stored_report="$(run ipc call health-test report)"
+! grep -Fq 'fixture-secret' <<<"$stored_report" \
+    || fail "adversarial snapshot leaked an unknown secret field: $stored_report"
+
+[[ "$(run ipc call health-test accept "$warning_snapshot" -1)" == "false" ]] \
+    || fail 'older generation replaced the current snapshot'
+state="$(run ipc call health-test status)"
+jq -e '.acceptedGeneration == 0 and .checks == ["integration.calendar", "panama.caffeine"]' \
+    >/dev/null <<<"$state" || fail "older generation altered accepted state: $state"
+
+[[ "$(run ipc call health-test accept '{not json' 1)" == "false" ]] \
+    || fail 'malformed snapshot was accepted'
+state="$(run ipc call health-test status)"
+jq -e '.diagnosticUnavailable == true and .checks == ["integration.calendar", "panama.caffeine"]' \
+    >/dev/null <<<"$state" || fail "malformed snapshot discarded the last valid checks: $state"
+
+before_generation="$(jq -r .generation <<<"$state")"
+run ipc call health-test queue >/dev/null
+state="$(run ipc call health-test status)"
+jq -e '.queuedRefresh == true and .generation == ($before + 1)' --argjson before "$before_generation" \
+    >/dev/null <<<"$state" || fail "two refreshes did not retain exactly one follow-up: $state"
+for _ in $(seq 1 120); do
+    state="$(run ipc call health-test status)"
+    jq -e '.busy == false and .generation == ($before + 2) and .queuedRefresh == false' --argjson before "$before_generation" \
+        >/dev/null <<<"$state" && break
+    sleep 0.1
+done
+jq -e '.busy == false and .generation == ($before + 2) and .queuedRefresh == false' --argjson before "$before_generation" \
+    >/dev/null <<<"$state" || fail "queued refresh did not run exactly once: $state"
+
+printf 'success\n' >"$repair_mode_file"
+rm -f "$repair_started_file" "$repair_release_file"
+repair_generation="$(jq -r .generation <<<"$state")"
+[[ "$(run ipc call health-test repair panama.caffeine)" == "true" ]] \
+    || fail 'repairable check was refused'
+for _ in $(seq 1 100); do
+    [[ -s "$repair_started_file" ]] && break
+    sleep 0.05
+done
+[[ -s "$repair_started_file" ]] || fail 'repair helper never reached the started marker'
+run ipc call health-test queue >/dev/null
+working_state="$(run ipc call health-test status)"
+jq -e '.repairingId == "panama.caffeine" and .queuedRefresh == true
+    and (.checkStates[] | select(.id == "panama.caffeine") | .status) == "warning"' \
+    >/dev/null <<<"$working_state" || fail "repair did not retain the degraded row while working: $working_state"
+: >"$repair_release_file"
+for _ in $(seq 1 120); do
+    state="$(run ipc call health-test status)"
+    jq -e '.busy == false and .generation == ($before + 1) and .queuedRefresh == false' --argjson before "$repair_generation" \
+        >/dev/null <<<"$state" && break
+    sleep 0.1
+done
+jq -e '.busy == false and .generation == ($before + 1) and .queuedRefresh == false
+    and .lastRepair == {schemaVersion:1, checkId:"panama.caffeine", accepted:true, exitCode:0, message:"Duplicate inhibitors were released."}
+    and (.checkStates[] | select(.id == "panama.caffeine") | .status) == "warning"' \
+    --argjson before "$repair_generation" >/dev/null <<<"$state" \
+    || fail "accepted repair was trusted before exactly one observed rescan: $state"
+
+# A syntactically valid command failure remains inline for Settings and still
+# receives exactly one observed rescan.
+printf 'failed\n' >"$repair_mode_file"
+failure_generation="$(jq -r .generation <<<"$state")"
+[[ "$(run ipc call health-test repair panama.caffeine)" == "true" ]] \
+    || fail 'second repairable check was refused'
+for _ in $(seq 1 120); do
+    state="$(run ipc call health-test status)"
+    jq -e '.busy == false and .generation == ($before + 1)' --argjson before "$failure_generation" \
+        >/dev/null <<<"$state" && break
+    sleep 0.1
+done
+jq -e '.lastRepair.checkId == "panama.caffeine"
+    and .lastRepair.accepted == true and .lastRepair.exitCode == 7
+    and .lastRepair.message == "Duplicate inhibitors could not be released."
+    and .generation == ($before + 1)' --argjson before "$failure_generation" \
+    >/dev/null <<<"$state" || fail "known repair failure was not retained inline: $state"
+[[ ! -e "$notification_log" || ! -s "$notification_log" ]] \
+    || fail 'Settings-originated repair emitted an external notification'
+
+# A malformed or mismatched helper response is contained and cannot masquerade
+# as recovery; it also schedules only one scan.
+printf 'mismatch\n' >"$repair_mode_file"
+mismatch_generation="$(jq -r .generation <<<"$state")"
+[[ "$(run ipc call health-test repair panama.caffeine)" == "true" ]] \
+    || fail 'mismatch repair fixture was refused'
+for _ in $(seq 1 120); do
+    state="$(run ipc call health-test status)"
+    jq -e '.busy == false and .generation == ($before + 1)' --argjson before "$mismatch_generation" \
+        >/dev/null <<<"$state" && break
+    sleep 0.1
+done
+jq -e '.lastRepair.checkId == "panama.caffeine" and .lastRepair.accepted == false
+    and .lastRepair.exitCode == 0 and .generation == ($before + 1)' \
+    --argjson before "$mismatch_generation" >/dev/null <<<"$state" \
+    || fail "mismatched repair JSON escaped containment: $state"
+
+# A refresh arriving after repair settlement but before the deferred mandatory
+# scan is coalesced into that scan instead of starting an extra generation.
+pending_race="$(run ipc call health-test pendingRefreshRace)"
+jq -e '.accepted == false' >/dev/null <<<"$pending_race" \
+    || fail "refresh escaped the post-repair pending window: $pending_race"
+pending_generation="$(jq -r .before <<<"$pending_race")"
+for _ in $(seq 1 120); do
+    state="$(run ipc call health-test status)"
+    jq -e '.busy == false and .generation == ($before + 1) and .queuedRefresh == false' \
+        --argjson before "$pending_generation" >/dev/null <<<"$state" && break
+    sleep 0.1
+done
+jq -e '.busy == false and .generation == ($before + 1) and .queuedRefresh == false' \
+    --argjson before "$pending_generation" >/dev/null <<<"$state" \
+    || fail "pending-window refresh created duplicate scans: $state"
+
+# External IPC cannot bypass an authored confirmation. The same current row is
+# still repairable through Settings' external=false path after UI confirmation.
+confirm_generation="$(jq -r .generation <<<"$state")"
+[[ "$(run ipc call health-test accept "$confirm_snapshot" "$confirm_generation")" == "true" ]] \
+    || fail 'confirmation fixture was rejected'
+before_repair_lines="$(wc -l <"$repair_log")"
+[[ "$(run ipc call health-test externalRepair desktop.quickshell)" == "false" ]] \
+    || fail 'external repair bypassed confirmation'
+[[ "$(wc -l <"$repair_log")" == "$before_repair_lines" ]] \
+    || fail 'external confirmation rejection started a process'
+[[ "$(run ipc call health-test repair desktop.quickshell)" == "true" ]] \
+    || fail 'confirmed Settings repair was refused'
+for _ in $(seq 1 120); do
+    state="$(run ipc call health-test status)"
+    jq -e '.busy == false and .generation == ($before + 1)' \
+        --argjson before "$confirm_generation" >/dev/null <<<"$state" && break
+    sleep 0.1
+done
+jq -e '.lastRepair == {schemaVersion:1, checkId:"desktop.quickshell", accepted:true, exitCode:0, message:"Panama shell restart was requested."}
+    and .generation == ($before + 1)' --argjson before "$confirm_generation" \
+    >/dev/null <<<"$state" || fail "confirmed Settings repair did not complete safely: $state"
+[[ "$(grep -Fc -- '--repair desktop.quickshell --json' "$repair_log")" == 1 ]] \
+    || fail 'confirmed Settings repair did not start exactly one repair process'
+
+[[ "$(run ipc call health-test repair unknown.check)" == "false" ]] \
+    || fail 'unknown check started a repair'
+[[ "$(run ipc call health-test repair integration.calendar)" == "false" ]] \
+    || fail 'non-repairable check started a repair'
+state="$(run ipc call health-test status)"
+jq -e '.repairingId == "" and .generation == ($before + 1)' --argjson before "$confirm_generation" \
+    >/dev/null <<<"$state" || fail "rejected repair altered process state: $state"
+
+python3 - "$service" <<'PY' || fail 'external repair failure notification is not bounded'
+import sys
+
+source = open(sys.argv[1], encoding="utf-8").read()
+assert 'if (failed && external && !failureNotification.running)' in source
+assert '"notify-send", "-a", "Panama", "-i", "dialog-error-symbolic"' in source
+assert '"Panama action failed", "The requested health repair could not be completed."' in source
+PY
+
+trap - EXIT
+cleanup
+printf 'health service contract: PASS\n'

tests/quickshell/health-ui-contract.sh

@@ -0,0 +1,429 @@
+#!/usr/bin/env bash
+
+# The approved Diagnostic Ledger is exercised in an isolated Quickshell
+# harness. It never maps or reloads the user's production shell.
+
+set -euo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+settings_dir="$repo_dir/config/dot/quickshell/modules/settings"
+bar_dir="$repo_dir/config/dot/quickshell/modules/bar"
+
+fail() {
+    printf 'health UI contract: %s\n' "$1" >&2
+    exit 1
+}
+
+for file in HealthPage.qml HealthSummary.qml HealthCheckRow.qml; do
+    [[ -f "$settings_dir/$file" ]] || fail "$file is missing"
+done
+[[ -f "$bar_dir/HealthIndicator.qml" ]] || fail 'HealthIndicator.qml is missing'
+
+python3 - "$bar_dir/Bar.qml" <<'PY' || fail 'health indicator is not immediately before activity in the bar'
+import re
+import sys
+
+source = open(sys.argv[1], encoding="utf-8").read()
+match = re.search(r'HealthIndicator\s*\{.*?\}\s*ActivityIndicator\s*\{', source, re.S)
+assert match is not None
+PY
+
+! rg -n '#[0-9a-fA-F]{3,8}' "$bar_dir/HealthIndicator.qml" >/dev/null \
+    || fail 'health indicator introduced colors outside Theme'
+! rg -n 'Behavior|Animation|Transition|pulse|shimmer' "$bar_dir/HealthIndicator.qml" >/dev/null \
+    || fail 'health indicator introduced motion'
+[[ ! -e "$settings_dir/ServicesPage.qml" ]] || fail 'ServicesPage.qml still exists'
+rg -Fq 'HealthPage 1.0 HealthPage.qml' "$settings_dir/qmldir" \
+    || fail 'HealthPage is not registered in the Settings QML module'
+rg -Fq 'HealthSummary 1.0 HealthSummary.qml' "$settings_dir/qmldir" \
+    || fail 'HealthSummary is not registered in the Settings QML module'
+rg -Fq 'HealthCheckRow 1.0 HealthCheckRow.qml' "$settings_dir/qmldir" \
+    || fail 'HealthCheckRow is not registered in the Settings QML module'
+! rg -Fq 'ServicesPage 1.0 ServicesPage.qml' "$settings_dir/qmldir" \
+    || fail 'retired ServicesPage remains registered in the Settings QML module'
+
+rg -Fq 'label: "System Health"' "$settings_dir/SettingsSidebar.qml" \
+    || fail 'sidebar does not label the stable services route System Health'
+rg -Fq 'onTapped: root.pageRequested("services")' "$settings_dir/SettingsSidebar.qml" \
+    || fail 'health footer does not open the stable services route'
+rg -Fq 'height: 54' "$settings_dir/SettingsSidebar.qml" \
+    || fail 'health footer lost its 54px target'
+rg -Fq 'onClicked: Health.copyReport()' "$settings_dir/HealthSummary.qml" \
+    || fail 'Copy Report does not use the redacted Health report path'
+rg -Fq 'text: "Checking…"' "$settings_dir/HealthSummary.qml" \
+    || fail 'refresh state is not expressed in text'
+rg -Fq 'implicitHeight: 126' "$settings_dir/HealthSummary.qml" \
+    || fail 'summary hero is not the approved stable 126px height'
+rg -Fq 'implicitHeight: 62' "$settings_dir/HealthCheckRow.qml" \
+    || fail 'health rows are below the approved 62px target'
+rg -Fq 'Health.refresh()' "$settings_dir/HealthPage.qml" \
+    || fail 'opening System Health does not request a fresh scan'
+rg -Fq 'SystemSettings.openGnomePanel("network")' "$settings_dir/HealthPage.qml" \
+    || fail 'Fedora ownership boundary does not open GNOME Settings'
+rg -Fq 'SystemSettings.openGnomePanel("system", "users")' "$settings_dir/HealthPage.qml" \
+    || fail 'Fedora ownership boundary lost the Users handoff'
+rg -Fq 'SystemSettings.openGnomePanel("sharing")' "$settings_dir/HealthPage.qml" \
+    || fail 'Fedora ownership boundary lost the Sharing handoff'
+rg -Fq 'SystemSettings.openGnomePanel("color")' "$settings_dir/HealthPage.qml" \
+    || fail 'Fedora ownership boundary lost the Colour profiles handoff'
+rg -Fq 'SystemSettings.openGnomePanel("wellbeing")' "$settings_dir/HealthPage.qml" \
+    || fail 'Fedora ownership boundary lost the Digital wellbeing handoff'
+# Exact authored handoffs are asserted above. Also prove every panel named by
+# this boundary is accepted by SystemSettings, so a typo cannot ship a dead
+# button even if its copy still looks correct.
+rg -Fq 'title: "Fedora system settings"' "$settings_dir/HealthPage.qml" \
+    || fail 'the Fedora ownership boundary card is gone'
+
+allowed="$(rg -o '"[a-z-]+"' "$repo_dir/config/dot/quickshell/services/SystemSettings.qml" \
+    | sed -n '/"\(applications\|background\|bluetooth\|color\|display\|keyboard\|mouse\|multitasking\|network\|notifications\|online-accounts\|power\|printers\|privacy\|search\|sharing\|sound\|system\|universal-access\|wacom\|wellbeing\|wifi\|wwan\)"/p' \
+    | tr -d '"' | sort -u)"
+
+while read -r panel; do
+    [[ -n "$panel" ]] || continue
+    grep -qx "$panel" <<<"$allowed" \
+        || fail "the Fedora card opens \"$panel\", which openGnomePanel does not allow -- that button does nothing"
+done < <(rg -o 'openGnomePanel\("([a-z-]+)"' -r '$1' "$settings_dir/HealthPage.qml" | sort -u)
+
+rg -q 'openGnomePanel\(' "$settings_dir/HealthPage.qml" \
+    || fail 'the Fedora ownership boundary does not open GNOME Settings at all'
+rg -Fq 'Health.repair(check.id, false)' "$settings_dir/HealthPage.qml" \
+    || fail 'Settings repair does not stay inline/non-external'
+rg -Fq 'ShellState.openSettings(check.action.target)' "$settings_dir/HealthPage.qml" \
+    || fail 'authored Settings targets are not routed directly'
+! rg -n '#[0-9a-fA-F]{3,8}' \
+    "$settings_dir/HealthPage.qml" \
+    "$settings_dir/HealthSummary.qml" \
+    "$settings_dir/HealthCheckRow.qml" >/dev/null \
+    || fail 'health UI introduced colors outside Theme'
+
+python3 - "$settings_dir/HealthPage.qml" "$settings_dir/HealthSummary.qml" \
+    "$settings_dir/HealthCheckRow.qml" <<'PY' || fail 'approved health structure or accessibility contract is missing'
+import sys
+
+page, summary, row = [open(path, encoding="utf-8").read() for path in sys.argv[1:]]
+
+labels = (
+    'if (status === "ok") return "Healthy";',
+    'if (status === "warning") return "Needs attention";',
+    'if (status === "error") return "Action required";',
+    'return "Not set up";',
+)
+assert all(label in page for label in labels)
+assert 'group: "desktop-foundation"' in page
+assert 'group: "input-media"' in page
+assert 'group: "integrations"' in page
+assert 'group: "panama-tools"' in page
+assert 'SettingsCard {' in page and 'SettingsCard {' in summary
+assert 'activeFocusOnTab: enabled' in summary
+assert 'Keys.onReturnPressed' in summary and 'Keys.onSpacePressed' in summary
+assert 'activeFocusOnTab: enabled' in row
+assert 'Keys.onReturnPressed' in row and 'Keys.onSpacePressed' in row
+assert 'border.width: activeFocus ? 2 : 1' in summary
+assert 'border.width: activeFocus ? 2 : 1' in row
+assert 'Health.diagnosticUnavailable ? "Retry"' in summary
+assert 'Health.lastCopyResult' in summary
+assert 'pendingConfirmation' in page
+assert 'ddc-permissions' in page
+PY
+
+fixture='{"schemaVersion":1,"generatedAt":"2026-08-18T12:00:00Z","summary":{"status":"error","healthy":2,"warnings":2,"errors":1,"unconfigured":1},"context":{"session":"hyprland","versions":[{"id":"quickshell","version":"0.3.0"}]},"checks":[{"id":"desktop.vicinae","group":"desktop-foundation","title":"Vicinae","status":"warning","detail":"The launcher service is stopped.","action":{"kind":"repair","label":"Restart Vicinae","confirm":false}},{"id":"desktop.quickshell","group":"desktop-foundation","title":"Quickshell","status":"error","detail":"Panama shell needs to restart.","action":{"kind":"repair","label":"Restart Panama","confirm":true}},{"id":"input.pipewire","group":"input-media","title":"PipeWire","status":"ok","detail":"Audio graph is responding."},{"id":"integration.bluebubbles","group":"integrations","title":"BlueBubbles","status":"unconfigured","detail":"Messaging integration has not been enabled."},{"id":"integration.calendar","group":"integrations","title":"Calendar","status":"warning","detail":"Calendar probe timed out.","action":{"kind":"open","label":"Open Date & Time","confirm":false,"target":"datetime"}},{"id":"panama.caffeine","group":"panama-tools","title":"Caffeine","status":"ok","detail":"No duplicate sleep inhibitors."}]}'
+
+state_home="$(mktemp -d /tmp/panama-health-ui.XXXXXX)"
+config_path="$state_home/quickshell"
+harness="$config_path/health-ui-harness.qml"
+helper="$state_home/panama-doctor"
+shell_log="$state_home/quickshell.log"
+fixture_home="$state_home/home"
+mkdir -p "$fixture_home"
+cp -a "$repo_dir/config/dot/quickshell" "$config_path"
+
+cat >"$helper" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+if [[ "${1:-}" == "--repair" ]]; then
+    sleep 0.35
+    printf '{"schemaVersion":1,"checkId":"%s","accepted":true,"exitCode":7,"message":"The authored repair failed."}\n' "$2"
+    exit 7
+fi
+sleep 1.5
+printf '%s\n' "$PANAMA_HEALTH_FIXTURE"
+EOF
+chmod +x "$helper"
+
+cat >"$harness" <<'QML'
+import Quickshell
+import Quickshell.Io
+import QtQuick
+
+import "modules/bar" as BarModule
+import qs.config
+import qs.modules.settings
+import qs.services
+
+ShellRoot {
+    id: root
+
+    Component.onCompleted: {
+        Health.startupScanEnabled = false;
+        ShellState.settingsPage = "services";
+        Health.consumeSnapshot(Quickshell.env("PANAMA_HEALTH_FIXTURE"), 100);
+    }
+
+    FloatingWindow {
+        title: "Panama Health UI Contract"
+        visible: true
+        implicitWidth: 980
+        implicitHeight: 820
+
+        SettingsShell {
+            id: settingsShell
+            anchors.fill: parent
+        }
+
+        BarModule.HealthIndicator {
+            id: healthIndicator
+            objectName: "health-indicator"
+        }
+    }
+
+    IpcHandler {
+        target: "health-ui-test"
+
+        function state(): string {
+            return JSON.stringify(settingsShell.healthDiagnostics);
+        }
+
+        function request(id: string): bool {
+            return settingsShell.requestHealthAction(id);
+        }
+
+        function indicatorMode(mode: string): bool {
+            const checkStatus = mode === "healthy" ? "ok" : (mode === "unconfigured" ? "unconfigured" : mode);
+            const overallStatus = mode === "warning" || mode === "error" ? mode : "healthy";
+            const snapshot = {
+                schemaVersion: 1,
+                generatedAt: "2026-08-18T12:00:00Z",
+                summary: {
+                    status: overallStatus,
+                    healthy: mode === "healthy" ? 1 : 0,
+                    warnings: mode === "warning" ? 1 : 0,
+                    errors: mode === "error" ? 1 : 0,
+                    unconfigured: mode === "unconfigured" ? 1 : 0
+                },
+                context: { session: "hyprland", versions: [] },
+                checks: [{
+                    id: "desktop.vicinae",
+                    group: "desktop-foundation",
+                    title: "Vicinae",
+                    status: checkStatus,
+                    detail: "Fixture observation."
+                }]
+            };
+            return Health.consumeSnapshot(JSON.stringify(snapshot), Health.acceptedGeneration + 1);
+        }
+
+        function indicatorState(): string {
+            return JSON.stringify({
+                visible: healthIndicator.visible,
+                width: healthIndicator.width,
+                implicitWidth: healthIndicator.implicitWidth,
+                issueCount: healthIndicator.issueCount,
+                statusText: healthIndicator.statusText,
+                accessibleLabel: healthIndicator.accessibleLabel,
+                tooltipText: healthIndicator.tooltipText,
+                warningTone: healthIndicator.tone === Theme.warn,
+                errorTone: healthIndicator.tone === Theme.danger,
+                activeFocusOnTab: healthIndicator.activeFocusOnTab
+            });
+        }
+
+        function activateIndicator(): string {
+            ShellState.settingsPage = "home";
+            ShellState.settingsOpen = false;
+            const generation = Health.generation;
+            healthIndicator.activated();
+            return JSON.stringify({
+                page: ShellState.settingsPage,
+                settingsOpen: ShellState.settingsOpen,
+                refreshRequested: Health.generation > generation || Health.queuedRefresh
+            });
+        }
+    }
+}
+QML
+
+run() {
+    PANAMA_HEALTH_FIXTURE="$fixture" PANAMA_HEALTH_HELPER="$helper" \
+        HOME="$fixture_home" XDG_STATE_HOME="$state_home" \
+        qs -p "$harness" "$@"
+}
+
+harness_pid=""
+cleanup() {
+    if [[ -n "$harness_pid" ]]; then
+        kill "$harness_pid" >/dev/null 2>&1 || true
+        for _ in $(seq 1 40); do
+            kill -0 "$harness_pid" >/dev/null 2>&1 || break
+            sleep 0.1
+        done
+    else
+        run kill >/dev/null 2>&1 || true
+    fi
+    rm -rf "$state_home"
+}
+trap cleanup EXIT
+
+PANAMA_HEALTH_FIXTURE="$fixture" PANAMA_HEALTH_HELPER="$helper" \
+    HOME="$fixture_home" XDG_STATE_HOME="$state_home" \
+    qs -p "$harness" --daemonize >"$shell_log" 2>&1
+for _ in $(seq 1 40); do
+    harness_pid="$(qs list --all 2>/dev/null | awk -v path="$harness" '
+        /Process ID:/ { pid = $3 }
+        index($0, "Config path: " path) { print pid; exit }
+    ')"
+    [[ "$harness_pid" =~ ^[0-9]+$ ]] && break
+    sleep 0.1
+done
+for _ in $(seq 1 60); do
+    run ipc show 2>/dev/null | rg -q '^target health-ui-test$' && break
+    sleep 0.1
+done
+run ipc show 2>/dev/null | rg -q '^target health-ui-test$' \
+    || { sed -n '1,200p' "$shell_log" >&2; fail 'isolated fixture did not start'; }
+
+checking_state="$(run ipc call health-ui-test state)"
+jq -e '
+    .renderedRows == [
+        {objectName:"health-check-row:issue:desktop.vicinae", id:"desktop.vicinae", section:"issue", statusText:"Needs attention"},
+        {objectName:"health-check-row:issue:desktop.quickshell", id:"desktop.quickshell", section:"issue", statusText:"Action required"},
+        {objectName:"health-check-row:issue:integration.calendar", id:"integration.calendar", section:"issue", statusText:"Needs attention"},
+        {objectName:"health-check-row:quiet:input.pipewire", id:"input.pipewire", section:"quiet", statusText:"Healthy"},
+        {objectName:"health-check-row:quiet:integration.bluebubbles", id:"integration.bluebubbles", section:"quiet", statusText:"Not set up"},
+        {objectName:"health-check-row:quiet:panama.caffeine", id:"panama.caffeine", section:"quiet", statusText:"Healthy"}
+    ]
+    and (.renderedRows | map(.id) | length) == 6
+    and (.renderedRows | map(.id) | unique | length) == 6
+    and .emptyQuietGroups == ["desktop-foundation"]
+    and .fedoraHandoffs == [
+        {id:"users", label:"Users", action:"Open users"},
+        {id:"sharing", label:"Sharing", action:"Open sharing"},
+        {id:"color", label:"Colour profiles", action:"Open colour"},
+        {id:"wellbeing", label:"Digital wellbeing", action:"Open wellbeing"}
+    ]
+    and .summaryHeight == 126
+    and (.rowHeights | length) == 6
+    and (.rowHeights | all(. >= 62))
+    and .checking == true
+    and .checkingText == "Checking…"
+' >/dev/null <<<"$checking_state" || fail "checking fixture did not render the approved state: $checking_state"
+
+checking_heights="$(jq -c .rowHeights <<<"$checking_state")"
+for _ in $(seq 1 40); do
+    settled_state="$(run ipc call health-ui-test state)"
+    [[ "$(jq -r .checking <<<"$settled_state")" == "false" ]] && break
+    sleep 0.1
+done
+sleep 0.1
+settled_state="$(run ipc call health-ui-test state)"
+[[ "$(jq -c .rowHeights <<<"$settled_state")" == "$checking_heights" ]] \
+    || fail 'row geometry changed after refresh settled'
+jq -e '
+    (.focusChain | index("health-copy-report-button")) != null
+    and (.focusChain | index("health-refresh-button")) != null
+    and (.focusChain | any(startswith("health-row-action:")))
+' >/dev/null <<<"$settled_state" || fail "actual focus-chain traversal does not reach hero and row actions: $settled_state"
+
+settled_heights="$(jq -c .rowHeights <<<"$settled_state")"
+[[ "$(run ipc call health-ui-test request desktop.vicinae)" == "true" ]] \
+    || fail 'inline repair fixture could not be requested'
+working_repair_state="$(run ipc call health-ui-test state)"
+jq -e '.renderedRows[] | select(.id == "desktop.vicinae") | .statusText == "Working…"' \
+    >/dev/null <<<"$working_repair_state" || fail "repair row did not show Working state: $working_repair_state"
+[[ "$(jq -c .rowHeights <<<"$working_repair_state")" == "$settled_heights" ]] \
+    || fail 'repair Working state changed row geometry'
+for _ in $(seq 1 40); do
+    failed_repair_state="$(run ipc call health-ui-test state)"
+    jq -e '.renderedRows[] | select(.id == "desktop.vicinae") | .statusText == "Repair failed"' \
+        >/dev/null <<<"$failed_repair_state" && break
+    sleep 0.1
+done
+jq -e '.renderedRows[] | select(.id == "desktop.vicinae") | .statusText == "Repair failed"' \
+    >/dev/null <<<"$failed_repair_state" || fail "repair failure was not shown inline: $failed_repair_state"
+[[ "$(jq -c .rowHeights <<<"$failed_repair_state")" == "$settled_heights" ]] \
+    || fail 'repair failure changed row geometry'
+[[ "$(jq -r '.renderedRows | map(.id) | unique | length' <<<"$failed_repair_state")" == 6 ]] \
+    || fail 'repair state duplicated a health action row'
+for _ in $(seq 1 40); do
+    failed_repair_state="$(run ipc call health-ui-test state)"
+    [[ "$(jq -r .checking <<<"$failed_repair_state")" == "false" ]] && break
+    sleep 0.1
+done
+[[ "$(jq -r .checking <<<"$failed_repair_state")" == "false" ]] \
+    || fail 'post-repair scan did not settle before the next action'
+
+[[ "$(run ipc call health-ui-test request desktop.quickshell)" == "true" ]] \
+    || fail 'restart confirmation fixture could not be requested'
+confirmation_state="$(run ipc call health-ui-test state)"
+jq -e '
+    .confirmationVisible == true
+    and .confirmationId == "desktop.quickshell"
+    and (.activatedRows | index("health-check-row:issue:desktop.quickshell")) != null
+    and (.activatedRows | map(select(endswith(":desktop.quickshell"))) | length) == 1
+' \
+    >/dev/null <<<"$confirmation_state" || fail 'Quickshell restart did not open confirmation sheet'
+
+for hidden_mode in healthy unconfigured; do
+    [[ "$(run ipc call health-ui-test indicatorMode "$hidden_mode")" == "true" ]] \
+        || fail "$hidden_mode indicator fixture was rejected"
+    hidden_state="$(run ipc call health-ui-test indicatorState)"
+    jq -e '
+        .visible == false
+        and .width == 0
+        and .implicitWidth == 0
+        and .issueCount == 0
+    ' >/dev/null <<<"$hidden_state" \
+        || fail "$hidden_mode state reserved bar space: $hidden_state"
+done
+
+[[ "$(run ipc call health-ui-test indicatorMode warning)" == "true" ]] \
+    || fail 'warning indicator fixture was rejected'
+warning_state="$(run ipc call health-ui-test indicatorState)"
+jq -e '
+    .visible == true
+    and .width > 0
+    and .implicitWidth > 0
+    and .issueCount == 1
+    and .statusText == "1 system health issue"
+    and .accessibleLabel == "System Health: 1 issue needs attention"
+    and .tooltipText == "System Health: 1 issue needs attention"
+    and .warningTone == true
+    and .errorTone == false
+    and .activeFocusOnTab == true
+' >/dev/null <<<"$warning_state" || fail "warning indicator is not the approved amber accessible capsule: $warning_state"
+
+[[ "$(run ipc call health-ui-test indicatorMode error)" == "true" ]] \
+    || fail 'error indicator fixture was rejected'
+error_state="$(run ipc call health-ui-test indicatorState)"
+jq -e '
+    .visible == true
+    and .issueCount == 1
+    and .accessibleLabel == "System Health: 1 issue requires action"
+    and .tooltipText == "System Health: 1 issue requires action"
+    and .warningTone == false
+    and .errorTone == true
+' >/dev/null <<<"$error_state" || fail "error indicator is not the approved red accessible capsule: $error_state"
+
+activation_state="$(run ipc call health-ui-test activateIndicator)"
+jq -e '
+    .page == "services"
+    and .settingsOpen == true
+    and .refreshRequested == true
+' >/dev/null <<<"$activation_state" || fail "indicator activation did not open and refresh System Health: $activation_state"
+
+if rg -i 'QQml|ReferenceError|TypeError|binding loop|failed to load component' "$shell_log"; then
+    fail 'isolated fixture emitted QML errors or warnings'
+fi
+
+trap - EXIT
+cleanup
+printf 'health UI contract: PASS\n'

tests/quickshell/kdeconnect_bridge_test.py

@@ -130,6 +130,134 @@ class KdeConnectBridgeTest(unittest.TestCase):
             ],
         )
 
+    def test_status_falls_back_to_paired_dbus_device_when_cli_is_empty(self) -> None:
+        device_id = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
+        device_path = f"/modules/kdeconnect/devices/{device_id}"
+
+        def runner(command: list[str], **_kwargs: object) -> subprocess.CompletedProcess[str]:
+            if command == ["kdeconnect-cli", "--list-devices"]:
+                return subprocess.CompletedProcess(command, 0, "0 devices found\n", "")
+            if command == ["busctl", "--user", "tree", "org.kde.kdeconnect"]:
+                return subprocess.CompletedProcess(command, 0, f"└─ {device_path}\n", "")
+            if command[:3] == ["busctl", "--user", "call"]:
+                return subprocess.CompletedProcess(command, 0, "as 0\n", "")
+            if command[:3] == ["busctl", "--user", "get-property"]:
+                values = {
+                    "name": 's "Fixture iPhone"\n',
+                    "type": 's "phone"\n',
+                    "isPaired": "b true\n",
+                    "isReachable": "b false\n",
+                    "supportedPlugins": (
+                        'as 3 "kdeconnect_share" "kdeconnect_clipboard" '
+                        '"kdeconnect_findmyphone"\n'
+                    ),
+                }
+                return subprocess.CompletedProcess(command, 0, values[command[-1]], "")
+            raise AssertionError(command)
+
+        self.assertEqual(
+            bridge.collect_status(runner),
+            {
+                "available": True,
+                "devices": [
+                    {
+                        "id": device_id,
+                        "name": "Fixture iPhone",
+                        "type": "phone",
+                        "paired": True,
+                        "reachable": False,
+                        "actions": ["clipboard", "ring", "share"],
+                    }
+                ],
+                "error": "",
+            },
+        )
+
+    def test_dbus_plugin_timeout_keeps_device_with_no_actions(self) -> None:
+        device_id = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
+
+        def runner(command: list[str], **_kwargs: object) -> subprocess.CompletedProcess[str]:
+            if command == ["busctl", "--user", "tree", "org.kde.kdeconnect"]:
+                path = f"/modules/kdeconnect/devices/{device_id}"
+                return subprocess.CompletedProcess(command, 0, f"└─ {path}\n", "")
+            if command[:3] == ["busctl", "--user", "call"]:
+                return subprocess.CompletedProcess(command, 0, "as 0\n", "")
+            if command[:3] == ["busctl", "--user", "get-property"]:
+                values = {
+                    "name": 's "Fixture iPhone"\n',
+                    "type": 's "phone"\n',
+                    "isPaired": "b true\n",
+                    "isReachable": "b false\n",
+                }
+                if command[-1] == "supportedPlugins":
+                    raise subprocess.TimeoutExpired(command, 8)
+                return subprocess.CompletedProcess(command, 0, values[command[-1]], "")
+            raise AssertionError(command)
+
+        self.assertEqual(bridge.dbus_devices(runner)[0]["actions"], [])
+
+    def test_cli_device_plugin_timeout_fails_closed(self) -> None:
+        device_id = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
+        listing = f"- Fixture iPhone: {device_id} (paired and reachable)\n"
+
+        def runner(command: list[str], **_kwargs: object) -> subprocess.CompletedProcess[str]:
+            if command == ["kdeconnect-cli", "--list-devices"]:
+                return subprocess.CompletedProcess(command, 0, listing, "")
+            raise subprocess.TimeoutExpired(command, 8)
+
+        status = bridge.collect_status(runner)
+
+        self.assertEqual(status["devices"][0]["type"], "phone")
+        self.assertEqual(status["devices"][0]["actions"], [])
+
+    def test_dbus_inventory_excludes_unpaired_peers(self) -> None:
+        device_id = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
+
+        def runner(command: list[str], **_kwargs: object) -> subprocess.CompletedProcess[str]:
+            if command == ["busctl", "--user", "tree", "org.kde.kdeconnect"]:
+                path = f"/modules/kdeconnect/devices/{device_id}"
+                return subprocess.CompletedProcess(command, 0, f"└─ {path}\n", "")
+            if command[:3] == ["busctl", "--user", "get-property"]:
+                values = {
+                    "name": 's "Nearby Stranger"\n',
+                    "type": 's "phone"\n',
+                    "isPaired": "b false\n",
+                    "isReachable": "b true\n",
+                }
+                return subprocess.CompletedProcess(command, 0, values[command[-1]], "")
+            raise AssertionError(command)
+
+        self.assertEqual(bridge.dbus_devices(runner), [])
+
+    def test_status_merges_paired_dbus_device_missing_from_cli(self) -> None:
+        cli_id = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
+        dbus_id = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
+        listing = f"- Fixture Laptop: {cli_id} (paired and reachable)\n"
+
+        def runner(command: list[str], **_kwargs: object) -> subprocess.CompletedProcess[str]:
+            if command == ["kdeconnect-cli", "--list-devices"]:
+                return subprocess.CompletedProcess(command, 0, listing, "")
+            if command == ["busctl", "--user", "tree", "org.kde.kdeconnect"]:
+                path = f"/modules/kdeconnect/devices/{dbus_id}"
+                return subprocess.CompletedProcess(command, 0, f"└─ {path}\n", "")
+            if command[:3] == ["busctl", "--user", "call"]:
+                return subprocess.CompletedProcess(command, 0, "as 0\n", "")
+            if command[:3] == ["busctl", "--user", "get-property"]:
+                is_dbus_device = dbus_id in command[4]
+                values = {
+                    "name": 's "Fixture iPhone"\n',
+                    "type": 's "phone"\n' if is_dbus_device else 's "desktop"\n',
+                    "isPaired": "b true\n",
+                    "isReachable": "b false\n",
+                    "supportedPlugins": "as 0\n",
+                }
+                return subprocess.CompletedProcess(command, 0, values[command[-1]], "")
+            raise AssertionError(command)
+
+        status = bridge.collect_status(runner)
+
+        self.assertEqual({device["id"] for device in status["devices"]}, {cli_id, dbus_id})
+
 
 if __name__ == "__main__":
     unittest.main()

tests/quickshell/migrations-contract.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+
+# Versioned upgrades for settings.json.
+#
+# The schema says what a setting IS; it cannot say what a setting USED to be.
+# Rename a key, change its units, or split one setting into two, and the stored
+# value stops being recognised -- and unrecognised keys are deliberately carried
+# through untouched, so the user's choice silently stops taking effect with
+# nothing to explain it.
+#
+# The list of migrations is empty today, which is exactly why this is tested
+# now: the first time it runs for real will be against somebody's actual
+# settings during an upgrade, and that is a poor moment to discover how it
+# behaves. The harness supplies fixture steps, including one that throws.
+
+set -uo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+harness="$repo_dir/config/dot/quickshell/migrations-harness.qml"
+
+fail() {
+    printf 'migrations contract: %s\n' "$1" >&2
+    exit 1
+}
+
+[[ -r "$harness" ]] || fail "the harness is missing: $harness"
+
+out="$(timeout 60 qs -p "$harness" 2>&1 | grep -o 'PANAMA-MIGRATIONS .*' | sed 's/^PANAMA-MIGRATIONS //')"
+[[ -n "$out" ]] || fail 'the harness produced no result'
+jq -e . >/dev/null 2>&1 <<<"$out" || fail "the harness did not emit JSON: $out"
+
+check() {
+    jq -e "$1" >/dev/null <<<"$out" || fail "$2 -- got $(jq -c "$3" <<<"$out")"
+}
+
+# A file written before versioning existed is stamped, NOT migrated. Running
+# the list against it would apply upgrades designed for schemas it never had.
+check '.unversioned.v == 1 and .unversioned.migrated == false and .unversioned.untouched == true' \
+    'a file with no schemaVersion must be stamped at the baseline without being migrated' '.unversioned'
+
+# The stamp has to reach disk. Reported as changed-but-not-migrated, it would
+# otherwise live only in memory and be redone on every single launch.
+check '.unversioned.changed == true' \
+    'stamping a pre-versioning file must be reported as a change so it gets written' '.unversioned'
+
+# A file from the future must not be rewritten at all.
+check '.future.changed == false' \
+    'a file from a newer version must not be written back' '.future'
+
+# Every step above the stored version runs, in order.
+check '.upgrade.v == 3 and .upgrade.b == 2 and .upgrade.c == "three" and .upgrade.count == 2' \
+    'an older file must run each pending step in order and end at the current version' '.upgrade'
+
+# Already current: nothing runs, nothing is touched.
+check '.current.migrated == false and .current.kept == true and .current.b == true' \
+    'a file already at the current version must be left alone' '.current'
+
+# A file from a NEWER Panama is left completely alone. Downgrading keys is not
+# something this can do correctly, and unknown keys are already preserved.
+check '.future.v == 9 and .future.migrated == false and .future.kept == true' \
+    'a file from a newer version must not be modified or downgraded' '.future'
+
+# A failing step stops at the last good version. Skipping past it would lose
+# the conversion forever; failing the whole load would cost every setting.
+check '.failure.v == 3 and .failure.count == 2 and .failure.kept == true' \
+    'a failing step must stop at the last good version, keeping the steps that succeeded' '.failure'
+
+# The promise that makes rollback safe.
+check '.preserved.kept == true' \
+    'a migration must not discard keys it does not recognise' '.preserved'
+
+printf 'migrations contract: PASS\n'

tests/quickshell/panama-action-contract.sh

@@ -148,6 +148,9 @@ assert_commands 'qs <ipc> <call> <overview> <open>'
 run_action settings
 assert_commands 'qs <ipc> <call> <settings> <open>'
 
+run_action health
+assert_commands 'qs <ipc> <call> <health> <open>'
+
 run_action dnd
 assert_commands $'qs <ipc> <call> <notifications> <dnd>\npanama-osd <message> <notifications-disabled-symbolic> <Do Not Disturb On>'
 
@@ -191,11 +194,13 @@ assert_commands $'qs <kill>\nquickshell <--daemonize>\nqs <ipc> <show>\npanama-o
 PANAMA_ACTION_TEST_FAIL_KILL=true run_action restart-shell
 assert_commands $'qs <kill>\nquickshell <--daemonize>\nqs <ipc> <show>\npanama-osd <message> <view-refresh-symbolic> <Panama Restarted>'
 
+usage_output="$work/usage.txt"
 if HOME="$work/home" PATH="$fake_bin:$PATH" PANAMA_ACTION_HELPER_DIR="$fake_bin" \
     PANAMA_ACTION_CONFIRM_ATTEMPTS=1 PANAMA_ACTION_CONFIRM_DELAY=0 PANAMA_ACTION_TEST_LOG="$command_log" \
-    "$dispatcher" definitely-not-an-action >/dev/null 2>&1; then
+    "$dispatcher" definitely-not-an-action > /dev/null 2>"$usage_output"; then
     fail 'unknown action was accepted'
 fi
+rg -q '\bhealth\b' "$usage_output" || fail 'health is missing from dispatcher usage'
 
 : >"$command_log"
 if PANAMA_ACTION_TEST_FAIL_QS=true HOME="$work/home" PATH="$fake_bin:$PATH" \

tests/quickshell/panama-command-install-contract.sh

@@ -25,8 +25,16 @@ trap cleanup EXIT
 if rg -q 'setup/scripts/link-vicinae-scripts' "$dotfile_installer"; then
     fail 'link-dotfiles also invokes the command installer'
 fi
-rg -Fq 'do "$script"; done' "$top_level_installer" \
+# Each setup stage must run in its OWN process, so strict-shell options and
-    || fail 'top-level installer sources setup scripts into one shared shell'
+# helper variables stay local to the script that owns them. What matters is
+# that the stages are executed rather than sourced -- this previously matched
+# the literal one-liner `do "$script"; done`, which failed the moment the loop
+# gained error reporting and spanned more than one line, despite the property
+# it cares about being unchanged.
+rg -q '(^|[^a-z-])(\.|source)\s+[^;]*setup/scripts' "$top_level_installer" \
+    && fail 'top-level installer sources setup scripts into one shared shell'
+rg -q '"\$script"' "$top_level_installer" \
+    || fail 'top-level installer does not execute the setup scripts'
 
 mkdir -p "$data_dir/scripts/panama" "$fake_bin"
 printf 'user-owned\n' >"$data_dir/scripts/panama/keep.sh"

tests/quickshell/panama-commands-contract.sh

@@ -24,6 +24,7 @@ declare -A expected=(
     [open-clipboard.sh]=clipboard
     [open-mission-control.sh]=overview
     [open-settings.sh]=settings
+    [check-system-health.sh]=health
     [toggle-dnd.sh]=dnd
     [toggle-caffeine.sh]=caffeine
     [toggle-night-light.sh]=night-light
@@ -72,6 +73,17 @@ for script_name in "${!expected[@]}"; do
     grep -Fxq '# @vicinae.icon ../../icons/hicolor/scalable/apps/panama-settings.svg' "$script" \
         || fail "$script_name does not use the Panama application identity"
 
+    if [[ $script_name == check-system-health.sh ]]; then
+        [[ $title == 'Panama: Check System Health' ]] \
+            || fail "health command has the wrong title: $title"
+        grep -Fxq '# @vicinae.schemaVersion 1' "$script" \
+            || fail 'health command does not use schema version 1'
+        grep -Fxq '# @vicinae.keywords ["health", "doctor", "repair", "services"]' "$script" \
+            || fail 'health command has the wrong search vocabulary'
+        grep -Fxq 'exec "$HOME/.config/quickshell/scripts/panama-action" health' "$script" \
+            || fail 'health command bypasses the stable dispatcher path'
+    fi
+
     : >"$dispatch_log"
     HOME="$work/home" PANAMA_COMMAND_TEST_LOG="$dispatch_log" "$script"
     dispatched="$(cat "$dispatch_log")"

tests/quickshell/panama-doctor-contract.sh

@@ -0,0 +1,732 @@
+#!/usr/bin/env bash
+
+# The doctor is deliberately exercised through its command boundary.  The
+# fixture commands include sensitive-looking output so this test proves the
+# report only retains explicitly parsed, non-sensitive observations.
+
+set -euo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+doctor="$repo_dir/config/dot/quickshell/scripts/panama-doctor"
+fixture_root="$repo_dir/tests/quickshell/fixtures/doctor"
+
+fail() {
+    printf 'panama doctor contract: %s\n' "$1" >&2
+    exit 1
+}
+
+fixture="$(mktemp -d /tmp/panama-doctor.XXXXXX)"
+child_pids=()
+cleanup() {
+    for pid in "${child_pids[@]}"; do
+        kill "$pid" >/dev/null 2>&1 || true
+        wait "$pid" >/dev/null 2>&1 || true
+    done
+    rm -rf "$fixture"
+}
+trap cleanup EXIT
+
+home="$fixture/home"
+config_home="$home/.config"
+state_home="$home/.local/state"
+runtime_dir="$fixture/runtime"
+bin_dir="$fixture/bin"
+data_home="$home/.local/share"
+
+mkdir -p "$config_home" "$state_home" "$runtime_dir" "$bin_dir" "$data_home/vicinae/scripts"
+cp "$fixture_root/bin/"* "$bin_dir/"
+chmod +x "$bin_dir"/*
+
+# These are intentionally tiny stand-ins for authored executable probes. The
+# named fixture scripts above cover probes whose output needs branch coverage.
+for tool in hyprctl wl-paste grim tesseract kitty nextcloud rustdesk kdeconnect-cli; do
+    cat >"$bin_dir/$tool" <<'EOF'
+#!/usr/bin/bash
+case "${0##*/}" in
+    hyprctl) printf 'Hyprland 0.50.0\n' ;;
+esac
+EOF
+    chmod +x "$bin_dir/$tool"
+done
+
+cat >"$bin_dir/flatpak" <<'EOF'
+#!/usr/bin/bash
+if [[ "${1:-}" == "info" && "${2:-}" == "app.bluebubbles.BlueBubbles" \
+        && "${PANAMA_DOCTOR_FIXTURE_BLUEBUBBLES:-installed}" == "installed" ]]; then
+    printf 'BlueBubbles fixture-secret-token\n'
+    exit 0
+fi
+exit 1
+EOF
+chmod +x "$bin_dir/flatpak"
+
+cat >"$bin_dir/calendar-agenda" <<'EOF'
+#!/usr/bin/bash
+if [[ "${1:-}" != "probe" ]]; then
+    exit 2
+fi
+case "${PANAMA_DOCTOR_FIXTURE_CALENDAR:-ready}" in
+    ready) printf '{"eds":true,"sourceRegistry":true,"enabledSources":2,"event":"fixture clipboard body"}\n' ;;
+    malformed) printf 'calendar AA:BB:CC:DD:EE:FF\n' ;;
+    timeout) /usr/bin/sleep 2; printf '{"enabledSources":2}\n' ;;
+    *) printf '{"eds":true,"sourceRegistry":true,"enabledSources":0}\n' ;;
+esac
+EOF
+chmod +x "$bin_dir/calendar-agenda"
+
+cat >"$bin_dir/panama-brightness" <<'EOF'
+#!/usr/bin/bash
+case "${PANAMA_DOCTOR_FIXTURE_BRIGHTNESS:-ready}" in
+    ready) printf '{"displays":[{"connector":"AA:BB:CC:DD:EE:FF"}],"error":""}\n' ;;
+    denied) printf '{"displays":[],"error":"fixture-secret-token"}\n' ;;
+    malformed) printf 'fixture clipboard body\n' ;;
+esac
+EOF
+chmod +x "$bin_dir/panama-brightness"
+
+mkdir -p "$config_home/autostart"
+touch "$config_home/autostart/nextcloud.desktop"
+for name in hypr quickshell uwsm vicinae; do
+    ln -s "$repo_dir/config/dot/$name" "$config_home/$name"
+done
+ln -s "$repo_dir/config/local/share/vicinae/scripts" "$data_home/vicinae/scripts/panama"
+
+run_doctor() {
+    HOME="$home" \
+    PATH="$bin_dir" \
+    XDG_CURRENT_DESKTOP=Hyprland \
+    PANAMA_HOME_ASSISTANT_URL='https://fixture.invalid' \
+    PANAMA_HOME_ASSISTANT_TOKEN='fixture-secret-token' \
+    PANAMA_DOCTOR_ROOT="$repo_dir" \
+    PANAMA_DOCTOR_HOME="$home" \
+    PANAMA_DOCTOR_CONFIG_HOME="$config_home" \
+    PANAMA_DOCTOR_STATE_HOME="$state_home" \
+    PANAMA_DOCTOR_RUNTIME_DIR="$runtime_dir" \
+    PANAMA_DOCTOR_PATH="$bin_dir" \
+    PANAMA_DOCTOR_TIMEOUT="${PANAMA_DOCTOR_TIMEOUT:-0.2}" \
+        /usr/bin/python3 "$doctor" "$@"
+}
+
+expected_order=$'desktop.hyprland\ndesktop.quickshell\ndesktop.notifications\ndesktop.portals\ndesktop.hyprpaper\ndesktop.hypridle\ndesktop.vicinae\ninput.pipewire\ninput.clipboard\ninput.wallpaper\ninput.capture\ninput.ocr\ninput.brightness\nintegration.nextcloud\nintegration.rustdesk\nintegration.kdeconnect\nintegration.bluebubbles\nintegration.home-assistant\nintegration.calendar\npanama.runtime-links\npanama.vicinae-commands\npanama.selected-terminal\npanama.selected-launcher\npanama.processes\npanama.caffeine'
+
+assert_schema_and_redaction() {
+    local snapshot="$1"
+    jq -e '.schemaVersion == 1
+      and (.generatedAt | type == "string")
+      and (.summary.status | IN("healthy", "warning", "error"))
+      and (.context.session | IN("hyprland", "other"))
+      and (.context.versions | type == "array")
+      and ([.checks[].id] | length == 25)
+      and ([.checks[].id] | unique | length == 25)
+      and ([.checks[].status] | all(IN("ok", "warning", "error", "unconfigured")))' \
+        >/dev/null <<<"$snapshot" || fail "invalid schema: $snapshot"
+    [[ "$(jq -r '.checks[].id' <<<"$snapshot")" == "$expected_order" ]] \
+        || fail "checks are not in the authored order"
+    ! grep -Fq 'fixture-secret-token' <<<"$snapshot" \
+        || fail 'report exposed a fixture secret'
+    ! grep -Fq 'fixture clipboard body' <<<"$snapshot" \
+        || fail 'report exposed clipboard or calendar content'
+    ! grep -Fq 'AA:BB:CC:DD:EE:FF' <<<"$snapshot" \
+        || fail 'report exposed a device address'
+}
+
+check_status() {
+    local snapshot="$1" id="$2" expected="$3"
+    [[ "$(jq -r --arg id "$id" '.checks[] | select(.id == $id) | .status' <<<"$snapshot")" == "$expected" ]] \
+        || fail "$id did not report $expected: $snapshot"
+}
+
+snapshot="$(run_doctor --json)"
+assert_schema_and_redaction "$snapshot"
+check_status "$snapshot" panama.vicinae-commands ok
+
+# The diagnostic follows the actual installer contract: the scripts parent is
+# a directory and only its Panama child is an authored link.
+rm "$data_home/vicinae/scripts/panama"
+unlinked_vicinae="$(run_doctor --json)"
+check_status "$unlinked_vicinae" panama.vicinae-commands warning
+PANAMA_PATH="$repo_dir" VICINAE_DATA_DIR="$data_home/vicinae" HOME="$home" \
+    PATH="$bin_dir:/usr/bin" "$repo_dir/setup/scripts/link-vicinae-scripts"
+relinked_vicinae="$(run_doctor --json)"
+check_status "$relinked_vicinae" panama.vicinae-commands ok
+[[ -L "$data_home/vicinae/scripts/panama" \
+    && "$(readlink "$data_home/vicinae/scripts/panama")" == "$repo_dir/config/local/share/vicinae/scripts" ]] \
+    || fail 'authored Vicinae helper did not create the diagnosed child link'
+
+# A healthy systemd-backed service stays healthy.
+check_status "$snapshot" desktop.hyprpaper ok
+
+# Arbitrary parent environment values are not propagated into probes.
+sealed_environment="$(PANAMA_DOCTOR_FIXTURE_PROBE_SECRET=fixture-secret-token run_doctor --json)"
+assert_schema_and_redaction "$sealed_environment"
+check_status "$sealed_environment" desktop.hyprpaper ok
+
+# An OS-level launch failure is contained as a check result, never a failed
+# doctor invocation or a partial snapshot.
+chmod 0644 "$bin_dir/systemctl"
+if ! launch_failure="$(run_doctor --json)"; then
+    chmod +x "$bin_dir/systemctl"
+    fail 'launch failure prevented the doctor from emitting JSON'
+fi
+chmod +x "$bin_dir/systemctl"
+assert_schema_and_redaction "$launch_failure"
+check_status "$launch_failure" desktop.hyprpaper error
+
+# A missing required executable is an error rather than a crash.
+mv "$bin_dir/qs" "$bin_dir/qs.off"
+missing_qs="$(run_doctor --json)"
+check_status "$missing_qs" desktop.quickshell error
+mv "$bin_dir/qs.off" "$bin_dir/qs"
+
+# Optional integrations stay neutral until the user configures them.
+rm "$config_home/autostart/nextcloud.desktop"
+unconfigured_nextcloud="$(run_doctor --json)"
+check_status "$unconfigured_nextcloud" integration.nextcloud unconfigured
+touch "$config_home/autostart/nextcloud.desktop"
+
+# A configured integration that stopped is actionable with an authored label,
+# never an application name or command derived from probe output.
+stopped_nextcloud="$(PANAMA_DOCTOR_FIXTURE_STOPPED=nextcloud.service run_doctor --json)"
+check_status "$stopped_nextcloud" integration.nextcloud warning
+jq -e '.checks[] | select(.id == "integration.nextcloud")
+  | .action == {kind:"open", label:"Open Nextcloud", confirm:false}' \
+    >/dev/null <<<"$stopped_nextcloud" || fail 'Nextcloud action was not authored'
+
+# DDC errors are classified without retaining connectors or bus addresses.
+denied_brightness="$(PANAMA_DOCTOR_FIXTURE_BRIGHTNESS=denied run_doctor --json)"
+check_status "$denied_brightness" input.brightness warning
+jq -e '.checks[] | select(.id == "input.brightness")
+  | .action == {kind:"instructions", label:"View setup instructions", confirm:false, target:"ddc-permissions"}' \
+    >/dev/null <<<"$denied_brightness" || fail 'DDC instructions were not authored'
+
+# A bounded probe timeout becomes a result, never a helper failure.
+timed_calendar="$(PANAMA_DOCTOR_FIXTURE_CALENDAR=timeout PANAMA_DOCTOR_TIMEOUT=0.05 run_doctor --json)"
+check_status "$timed_calendar" integration.calendar warning
+jq -e '.checks[] | select(.id == "integration.calendar")
+  | .action == {kind:"open", label:"Open Date & Time", confirm:false, target:"datetime"}' \
+    >/dev/null <<<"$timed_calendar" || fail 'calendar action was not authored'
+
+# Exact Panama/Caffeine inhibitor rows detect duplicates without exposing PIDs.
+duplicated_caffeine="$(PANAMA_DOCTOR_FIXTURE_CAFFEINE=duplicate run_doctor --json)"
+check_status "$duplicated_caffeine" panama.caffeine warning
+jq -e '.checks[] | select(.id == "panama.caffeine")
+  | .action == {kind:"repair", label:"Release duplicate inhibitors", confirm:false}' \
+    >/dev/null <<<"$duplicated_caffeine" || fail 'Caffeine repair action was not authored'
+! jq -r '.checks[] | select(.id == "panama.caffeine") | .detail' <<<"$duplicated_caffeine" | grep -Eq '[0-9]{3,}' \
+    || fail 'Caffeine detail exposed inhibitor PIDs'
+
+# Process counts use only exact authored names and never expose command lines or PIDs.
+duplicated_processes="$(PANAMA_DOCTOR_FIXTURE_PROCESSES=quickshell:duplicate run_doctor --json)"
+check_status "$duplicated_processes" panama.processes warning
+! jq -r '.checks[] | select(.id == "panama.processes") | .detail' <<<"$duplicated_processes" | grep -Eq '[0-9]{3,}' \
+    || fail 'process detail exposed a PID'
+
+# Invalid output for a non-Quickshell authored process is not a normal zero
+# count that can be hidden by the running Quickshell process.
+malformed_processes="$(PANAMA_DOCTOR_FIXTURE_PROCESSES=hyprpaper:malformed run_doctor --json)"
+check_status "$malformed_processes" panama.processes warning
+
+# Panama/Caffeine-shaped rows that do not satisfy the fixed inhibitor schema
+# are unavailable rather than reported as a healthy no-inhibitor state.
+malformed_caffeine="$(PANAMA_DOCTOR_FIXTURE_CAFFEINE=malformed run_doctor --json)"
+check_status "$malformed_caffeine" panama.caffeine warning
+
+# A decoding error raised inside a concurrent probe is converted to a complete
+# snapshot rather than escaping from Future.result().
+if ! invalid_probe="$(PANAMA_DOCTOR_FIXTURE_BUS=invalid-utf8 run_doctor --json)"; then
+    fail 'unexpected probe exception prevented the doctor from emitting JSON'
+fi
+assert_schema_and_redaction "$invalid_probe"
+check_status "$invalid_probe" desktop.portals warning
+
+# Configured Home Assistant failures route to the exact authored Settings page.
+rm "$config_home/quickshell"
+mkdir -p "$config_home/quickshell/scripts"
+home_assistant_failure="$(run_doctor --json)"
+check_status "$home_assistant_failure" integration.home-assistant warning
+jq -e '.checks[] | select(.id == "integration.home-assistant")
+  | .action == {kind:"open", label:"Open Home settings", confirm:false, target:"home-phone"}' \
+    >/dev/null <<<"$home_assistant_failure" || fail 'Home Assistant action was not routed to home-phone'
+
+# Invalid probe text is contained in its own check and never copied to JSON.
+malformed_calendar="$(PANAMA_DOCTOR_FIXTURE_CALENDAR=malformed run_doctor --json)"
+check_status "$malformed_calendar" integration.calendar warning
+assert_schema_and_redaction "$malformed_calendar"
+
+summary="$(run_doctor --summary)"
+[[ "$summary" =~ ^Panama\ system\ health:\ (healthy|warning|error)\ \([0-9]+\ ok,\ [0-9]+\ warnings,\ [0-9]+\ errors,\ [0-9]+\ unconfigured\)$ ]] \
+    || fail "summary is not concise: $summary"
+
+# Repairs run against a second, disposable Panama root. Every process boundary
+# records its argv, and every filesystem assertion is confined to this fixture.
+repair_root="$home/.local/share/Panama"
+repair_log="$runtime_dir/repair.log"
+mkdir -p "$repair_root/config/dot" "$repair_root/config/local/share/vicinae/scripts" \
+    "$repair_root/setup/scripts"
+for name in hypr quickshell uwsm vicinae; do
+    mkdir -p "$repair_root/config/dot/$name"
+done
+cp "$repo_dir/setup/scripts/link-vicinae-scripts" "$repair_root/setup/scripts/link-vicinae-scripts"
+
+mv "$bin_dir/systemctl" "$bin_dir/systemctl-probe"
+cat >"$bin_dir/systemctl" <<'EOF'
+#!/usr/bin/bash
+set -euo pipefail
+if [[ "${1:-}" == "--user" && "${2:-}" == "restart" ]]; then
+    printf 'systemctl' >>"$XDG_RUNTIME_DIR/repair.log"
+    printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
+    printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
+    [[ ! -e "$XDG_RUNTIME_DIR/fail-repair" ]] || exit 5
+    exit 0
+fi
+exec "${0%/*}/systemctl-probe" "$@"
+EOF
+
+cat >"$bin_dir/panama-action" <<'EOF'
+#!/usr/bin/bash
+set -euo pipefail
+printf 'panama-action' >>"$XDG_RUNTIME_DIR/repair.log"
+printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
+printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
+EOF
+
+cat >"$bin_dir/systemd-inhibit" <<'EOF'
+#!/usr/bin/bash
+set -euo pipefail
+printf 'systemd-inhibit' >>"$XDG_RUNTIME_DIR/repair.log"
+printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
+printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
+count_file="$XDG_RUNTIME_DIR/caffeine-list-count"
+count=0
+[[ ! -f "$count_file" ]] || read -r count <"$count_file"
+count=$((count + 1))
+printf '%s\n' "$count" >"$count_file"
+read -r preserved duplicate <"$XDG_RUNTIME_DIR/caffeine-pids"
+uid="$(/usr/bin/id -u)"
+mode="$(<"$XDG_RUNTIME_DIR/caffeine-mode")"
+if [[ "$mode" == disappear && "$count" -ge 2 ]]; then
+    /usr/bin/touch "$XDG_RUNTIME_DIR/release-disappearing-pid"
+    for _ in $(/usr/bin/seq 1 100); do
+        [[ ! -e "/proc/$duplicate" ]] && break
+        /usr/bin/sleep 0.01
+    done
+fi
+preserved_comm=systemd-inhibit
+if [[ "$mode" == preserve-altered && "$count" -ge 2 ]]; then
+    preserved_comm=changed-command
+fi
+printf 'Panama %s fixture-user %s %s sleep:idle Caffeine block\n' "$uid" "$preserved" "$preserved_comm"
+if [[ "$mode" != multiplicity || "$count" -lt 2 ]]; then
+    printf 'Panama %s fixture-user %s systemd-inhibit sleep:idle Caffeine block\n' "$uid" "$preserved"
+fi
+if [[ "$mode" == altered && "$count" -ge 2 ]]; then
+    printf 'Panama %s fixture-user %s systemd-inhibit sleep:idle Other block\n' "$uid" "$duplicate"
+else
+    printf 'Panama %s fixture-user %s systemd-inhibit sleep:idle Caffeine block\n' "$uid" "$duplicate"
+fi
+printf 'Other %s fixture-user 4999 systemd-inhibit sleep:idle Caffeine block\n' "$uid"
+printf 'Panama 99999 fixture-user 4998 systemd-inhibit sleep:idle Caffeine block\n'
+printf 'Panama %s fixture-user 4997 systemd-inhibit sleep:idle Other block\n' "$uid"
+printf 'Panama %s fixture-user 4996 systemd-inhibit sleep:idle Caffeine delay\n' "$uid"
+EOF
+
+chmod +x "$bin_dir/systemctl" "$bin_dir/panama-action" \
+    "$bin_dir/systemd-inhibit" "$repair_root/setup/scripts/link-vicinae-scripts"
+
+run_repair() {
+    HOME="$home" \
+    PATH="$bin_dir:/usr/bin" \
+    XDG_CURRENT_DESKTOP=Hyprland \
+    PANAMA_DOCTOR_ROOT="$repair_root" \
+    PANAMA_DOCTOR_HOME="$home" \
+    PANAMA_DOCTOR_CONFIG_HOME="$config_home" \
+    PANAMA_DOCTOR_STATE_HOME="$state_home" \
+    PANAMA_DOCTOR_RUNTIME_DIR="$runtime_dir" \
+    PANAMA_DOCTOR_PATH="$bin_dir:/usr/bin" \
+    PANAMA_DOCTOR_TIMEOUT=0.2 \
+        /usr/bin/python3 "$doctor" "$@"
+}
+
+repair_output=""
+repair_status=0
+invoke_repair() {
+    set +e
+    repair_output="$(run_repair --repair "$1" --json)"
+    repair_status=$?
+    set -e
+}
+
+assert_repair_result() {
+    local id="$1" accepted="$2" exit_code="$3"
+    jq -e --arg id "$id" --argjson accepted "$accepted" --argjson exitCode "$exit_code" '
+      (keys | sort) == ["accepted", "checkId", "exitCode", "message", "schemaVersion"]
+      and .schemaVersion == 1
+      and .checkId == $id
+      and .accepted == $accepted
+      and .exitCode == $exitCode
+      and (.message | type == "string" and length > 0)
+    ' >/dev/null <<<"$repair_output" || fail "invalid repair result for $id: $repair_output"
+}
+
+for repair_case in \
+    'desktop.hyprpaper|systemctl|--user|restart|hyprpaper.service' \
+    'desktop.hypridle|systemctl|--user|restart|hypridle.service' \
+    'desktop.vicinae|systemctl|--user|restart|vicinae.service' \
+    'desktop.quickshell|panama-action|restart-shell'; do
+    IFS='|' read -r repair_id executable arg1 arg2 arg3 <<<"$repair_case"
+    : >"$repair_log"
+    invoke_repair "$repair_id"
+    [[ "$repair_status" == 0 ]] || fail "$repair_id returned $repair_status"
+    assert_repair_result "$repair_id" true 0
+    expected="$executable|$arg1"
+    [[ -z "$arg2" ]] || expected+="|$arg2"
+    [[ -z "$arg3" ]] || expected+="|$arg3"
+    [[ "$(<"$repair_log")" == "$expected" ]] \
+        || fail "$repair_id argv was not exact: $(<"$repair_log")"
+done
+
+# Known process failures still return complete JSON and preserve the command's
+# exit status for the QML state machine.
+touch "$runtime_dir/fail-repair"
+: >"$repair_log"
+invoke_repair desktop.vicinae
+rm "$runtime_dir/fail-repair"
+[[ "$repair_status" == 5 ]] || fail "failed repair returned $repair_status instead of 5"
+assert_repair_result desktop.vicinae true 5
+[[ "$(<"$repair_log")" == 'systemctl|--user|restart|vicinae.service' ]] \
+    || fail 'failed repair changed the authored argv'
+
+# The real authored Vicinae helper converges the exact child link diagnosed by
+# panama-doctor under the isolated HOME.
+rm -f "$data_home/vicinae/scripts/panama"
+before_vicinae_repair="$(run_repair --json)"
+check_status "$before_vicinae_repair" panama.vicinae-commands warning
+invoke_repair panama.vicinae-commands
+[[ "$repair_status" == 0 ]] || fail "Vicinae command repair returned $repair_status"
+assert_repair_result panama.vicinae-commands true 0
+after_vicinae_repair="$(run_repair --json)"
+check_status "$after_vicinae_repair" panama.vicinae-commands ok
+[[ -L "$data_home/vicinae/scripts/panama" \
+    && "$(readlink "$data_home/vicinae/scripts/panama")" == "$repair_root/config/local/share/vicinae/scripts" ]] \
+    || fail 'Vicinae repair did not install the diagnosed child link'
+
+# Runtime-link repair may replace only absent links or symlinks whose lexical
+# target proves Panama ownership. Every other object remains untouched.
+for name in hypr quickshell uwsm vicinae; do
+    path="$config_home/$name"
+    if [[ -e "$path" || -L "$path" ]]; then
+        mv "$path" "$fixture/pre-repair-$name"
+    fi
+done
+ln -s "$repair_root/config/dot/hypr" "$config_home/hypr"
+correct_inode="$(stat -c %i "$config_home/hypr")"
+ln -s "$repair_root/config/dot/quickshell" "$config_home/uwsm"
+ln -s "$fixture/external-broken-link" "$config_home/vicinae"
+ln -s "$fixture/untouched" "$config_home/not-panama"
+: >"$repair_log"
+invoke_repair panama.runtime-links
+[[ "$repair_status" == 1 ]] || fail "blocked runtime-link repair returned $repair_status"
+assert_repair_result panama.runtime-links true 1
+[[ -L "$config_home/hypr" && "$(readlink "$config_home/hypr")" == "$repair_root/config/dot/hypr" ]] \
+    || fail 'correct runtime link changed'
+[[ "$(stat -c %i "$config_home/hypr")" == "$correct_inode" ]] \
+    || fail 'correct runtime link was replaced instead of left untouched'
+[[ -L "$config_home/quickshell" && "$(readlink "$config_home/quickshell")" == "$repair_root/config/dot/quickshell" ]] \
+    || fail 'absent quickshell link was not created'
+[[ -L "$config_home/uwsm" && "$(readlink "$config_home/uwsm")" == "$repair_root/config/dot/uwsm" ]] \
+    || fail 'provably Panama-owned stale link was not repaired'
+[[ -L "$config_home/vicinae" && "$(readlink "$config_home/vicinae")" == "$fixture/external-broken-link" ]] \
+    || fail 'external broken symlink was replaced'
+[[ -L "$config_home/not-panama" && "$(readlink "$config_home/not-panama")" == "$fixture/untouched" ]] \
+    || fail 'runtime-link repair touched an unauthored link name'
+[[ ! -s "$repair_log" ]] || fail 'runtime-link repair launched a process'
+
+# Regular files and directories also remain untouched.
+rm "$config_home/vicinae"
+rm "$config_home/uwsm"
+printf 'user-owned file\n' >"$config_home/uwsm"
+mkdir "$config_home/vicinae"
+invoke_repair panama.runtime-links
+[[ "$repair_status" == 1 ]] || fail 'file/directory blockers did not make repair incomplete'
+[[ -f "$config_home/uwsm" && "$(<"$config_home/uwsm")" == 'user-owned file' ]] \
+    || fail 'runtime-link repair replaced a regular file'
+[[ -d "$config_home/vicinae" && ! -L "$config_home/vicinae" ]] \
+    || fail 'runtime-link repair replaced a user-owned directory'
+
+# An injected exchange failure occurs after the authored candidate symlink is
+# made; the original link must still be intact.
+/usr/bin/python3 - "$doctor" "$repair_root" "$fixture/atomic-config" <<'PY' \
+    || fail 'atomic replacement failure did not preserve the original link'
+import importlib.util
+import importlib.machinery
+import os
+import sys
+from pathlib import Path
+
+doctor_path, root_text, config_text = sys.argv[1:]
+loader = importlib.machinery.SourceFileLoader("panama_doctor_contract", doctor_path)
+spec = importlib.util.spec_from_loader(loader.name, loader)
+module = importlib.util.module_from_spec(spec)
+sys.modules[spec.name] = module
+loader.exec_module(module)
+root = Path(root_text)
+config_home = Path(config_text)
+config_home.mkdir(parents=True)
+destination = config_home / "hypr"
+original = root / "config/dot/quickshell"
+destination.symlink_to(original, target_is_directory=True)
+config = module.DoctorConfig(root, config_home.parent, config_home, config_home.parent / "state", config_home.parent / "runtime", "", 0.2)
+real_exchange = module.rename_exchange
+module.rename_exchange = lambda source, target: (_ for _ in ()).throw(OSError("fixture exchange failure"))
+try:
+    result = module.repair_runtime_links(config)
+finally:
+    module.rename_exchange = real_exchange
+assert result.exit_code == 1
+assert destination.is_symlink()
+assert os.readlink(destination) == str(original)
+assert not list(config_home.glob(".panama-link-*"))
+PY
+
+# A deterministic swap at the ownership/replacement boundary must be detected
+# from the exchanged-out object and rolled back, preserving the external link.
+/usr/bin/python3 - "$doctor" "$repair_root" "$fixture/toctou-config" "$fixture/external-race-target" <<'PY' \
+    || fail 'runtime-link exchange did not restore a boundary-swapped external link'
+import importlib.machinery
+import importlib.util
+import os
+import sys
+from pathlib import Path
+
+doctor_path, root_text, config_text, external_text = sys.argv[1:]
+loader = importlib.machinery.SourceFileLoader("panama_doctor_toctou", doctor_path)
+spec = importlib.util.spec_from_loader(loader.name, loader)
+module = importlib.util.module_from_spec(spec)
+sys.modules[spec.name] = module
+loader.exec_module(module)
+root = Path(root_text)
+config_home = Path(config_text)
+config_home.mkdir(parents=True)
+for name, relative in module.RUNTIME_LINK_TARGETS:
+    (config_home / name).symlink_to(root / relative, target_is_directory=True)
+destination = config_home / "uwsm"
+destination.unlink()
+destination.symlink_to(root / "config/dot/quickshell", target_is_directory=True)
+external = Path(external_text)
+real_exchange = module.rename_exchange
+first = True
+
+def race_exchange(candidate, target):
+    global first
+    if first:
+        first = False
+        target.unlink()
+        target.symlink_to(external, target_is_directory=True)
+    real_exchange(candidate, target)
+
+module.rename_exchange = race_exchange
+config = module.DoctorConfig(root, config_home.parent, config_home, config_home.parent / "state", config_home.parent / "runtime", "", 0.2)
+try:
+    result = module.repair_runtime_links(config)
+finally:
+    module.rename_exchange = real_exchange
+assert result.exit_code == 1
+assert destination.is_symlink()
+assert os.readlink(destination) == str(external)
+assert not list(config_home.glob(".panama-link-*"))
+PY
+
+# Caffeine repair deduplicates rows, pins each distinct duplicate with a
+# pidfd, revalidates authored metadata, and signals only the duplicate.
+/usr/bin/sleep 30 &
+preserved_pid=$!
+child_pids+=("$preserved_pid")
+/usr/bin/sleep 30 &
+duplicate_pid=$!
+child_pids+=("$duplicate_pid")
+printf '%s %s\n' "$preserved_pid" "$duplicate_pid" >"$runtime_dir/caffeine-pids"
+printf 'dedupe\n' >"$runtime_dir/caffeine-mode"
+rm -f "$runtime_dir/caffeine-list-count"
+: >"$repair_log"
+invoke_repair panama.caffeine
+[[ "$repair_status" == 0 ]] || fail "Caffeine repair returned $repair_status"
+assert_repair_result panama.caffeine true 0
+expected_caffeine=$'systemd-inhibit|--list|--no-pager|--no-legend\nsystemd-inhibit|--list|--no-pager|--no-legend'
+[[ "$(<"$repair_log")" == "$expected_caffeine" ]] \
+    || fail "Caffeine repair did not preserve/filter exact inhibitors: $(<"$repair_log")"
+kill -0 "$preserved_pid" >/dev/null 2>&1 || fail 'repeated inhibitor rows killed the preserved process'
+for _ in $(seq 1 40); do
+    kill -0 "$duplicate_pid" >/dev/null 2>&1 || break
+    sleep 0.05
+done
+! kill -0 "$duplicate_pid" >/dev/null 2>&1 || fail 'distinct duplicate inhibitor was not terminated'
+
+# Changed second-list metadata invalidates the candidate before any signal.
+/usr/bin/sleep 30 &
+altered_preserved=$!
+child_pids+=("$altered_preserved")
+/usr/bin/sleep 30 &
+altered_duplicate=$!
+child_pids+=("$altered_duplicate")
+printf '%s %s\n' "$altered_preserved" "$altered_duplicate" >"$runtime_dir/caffeine-pids"
+printf 'altered\n' >"$runtime_dir/caffeine-mode"
+rm -f "$runtime_dir/caffeine-list-count"
+invoke_repair panama.caffeine
+[[ "$repair_status" == 1 ]] || fail 'altered inhibitor metadata was not safely refused'
+assert_repair_result panama.caffeine true 1
+kill -0 "$altered_preserved" >/dev/null 2>&1 || fail 'metadata refusal signaled the preserved process'
+kill -0 "$altered_duplicate" >/dev/null 2>&1 || fail 'metadata refusal signaled the candidate process'
+
+# Changing metadata on the preserved row is also a full-identity mismatch,
+# even though every duplicate PID remains present.
+/usr/bin/sleep 30 &
+preserve_changed_keep=$!
+child_pids+=("$preserve_changed_keep")
+/usr/bin/sleep 30 &
+preserve_changed_duplicate=$!
+child_pids+=("$preserve_changed_duplicate")
+printf '%s %s\n' "$preserve_changed_keep" "$preserve_changed_duplicate" >"$runtime_dir/caffeine-pids"
+printf 'preserve-altered\n' >"$runtime_dir/caffeine-mode"
+rm -f "$runtime_dir/caffeine-list-count"
+invoke_repair panama.caffeine
+[[ "$repair_status" == 1 ]] || fail 'preserved-row metadata change was not safely refused'
+assert_repair_result panama.caffeine true 1
+kill -0 "$preserve_changed_keep" >/dev/null 2>&1 || fail 'preserved-row mismatch signaled the preserved process'
+kill -0 "$preserve_changed_duplicate" >/dev/null 2>&1 || fail 'preserved-row mismatch signaled the duplicate process'
+
+# A repeated exact row disappearing between lists changes multiplicity and is
+# refused before signaling any pinned duplicate.
+/usr/bin/sleep 30 &
+multiplicity_keep=$!
+child_pids+=("$multiplicity_keep")
+/usr/bin/sleep 30 &
+multiplicity_duplicate=$!
+child_pids+=("$multiplicity_duplicate")
+printf '%s %s\n' "$multiplicity_keep" "$multiplicity_duplicate" >"$runtime_dir/caffeine-pids"
+printf 'multiplicity\n' >"$runtime_dir/caffeine-mode"
+rm -f "$runtime_dir/caffeine-list-count"
+invoke_repair panama.caffeine
+[[ "$repair_status" == 1 ]] || fail 'inhibitor row multiplicity change was not safely refused'
+assert_repair_result panama.caffeine true 1
+kill -0 "$multiplicity_keep" >/dev/null 2>&1 || fail 'multiplicity mismatch signaled the preserved process'
+kill -0 "$multiplicity_duplicate" >/dev/null 2>&1 || fail 'multiplicity mismatch signaled the duplicate process'
+
+# The production pidfd release function preflights every candidate before any
+# SIGTERM. A refused second preflight leaves both disposable children alive.
+/usr/bin/sleep 30 &
+preflight_first=$!
+child_pids+=("$preflight_first")
+/usr/bin/sleep 30 &
+preflight_second=$!
+child_pids+=("$preflight_second")
+/usr/bin/python3 - "$doctor" "$preflight_first" "$preflight_second" <<'PY' \
+    || fail 'pidfd preflight failure signaled a disposable duplicate'
+import errno
+import importlib.machinery
+import importlib.util
+import os
+import signal
+import sys
+
+doctor_path = sys.argv[1]
+pids = [int(value) for value in sys.argv[2:]]
+loader = importlib.machinery.SourceFileLoader("panama_doctor_preflight", doctor_path)
+spec = importlib.util.spec_from_loader(loader.name, loader)
+module = importlib.util.module_from_spec(spec)
+sys.modules[spec.name] = module
+loader.exec_module(module)
+pidfds = [os.pidfd_open(pid, 0) for pid in pids]
+calls = []
+
+def sender(pidfd, sig, siginfo, flags):
+    calls.append(sig)
+    if sig == 0 and pidfd == pidfds[1]:
+        raise PermissionError(errno.EPERM, "fixture preflight refusal")
+    signal.pidfd_send_signal(pidfd, sig, siginfo, flags)
+
+try:
+    outcome = module.signal_caffeine_pidfds(pidfds, sender)
+finally:
+    for pidfd in pidfds:
+        os.close(pidfd)
+assert outcome == "preflight-failed"
+assert calls == [0, 0]
+for pid in pids:
+    os.kill(pid, 0)
+PY
+kill -0 "$preflight_first" >/dev/null 2>&1 || fail 'preflight refusal killed the first duplicate'
+kill -0 "$preflight_second" >/dev/null 2>&1 || fail 'preflight refusal killed the second duplicate'
+
+# A candidate that disappears after pidfd acquisition and second-list request
+# is a safe failure; an unrelated disposable process must remain untouched.
+/usr/bin/sleep 30 &
+unrelated_pid=$!
+child_pids+=("$unrelated_pid")
+(
+    /usr/bin/sleep 30 &
+    disappearing_pid=$!
+    trap 'kill "$disappearing_pid" >/dev/null 2>&1 || true; wait "$disappearing_pid" >/dev/null 2>&1 || true' EXIT
+    printf '%s\n' "$disappearing_pid" >"$runtime_dir/disappearing-pid"
+    while [[ ! -e "$runtime_dir/release-disappearing-pid" ]]; do
+        /usr/bin/sleep 0.01
+    done
+    kill "$disappearing_pid"
+    wait "$disappearing_pid" >/dev/null 2>&1 || true
+    trap - EXIT
+) &
+disappearance_controller=$!
+child_pids+=("$disappearance_controller")
+for _ in $(seq 1 100); do
+    [[ -s "$runtime_dir/disappearing-pid" ]] && break
+    sleep 0.01
+done
+[[ -s "$runtime_dir/disappearing-pid" ]] || fail 'disappearing PID fixture did not start'
+disappearing_pid="$(<"$runtime_dir/disappearing-pid")"
+printf '%s %s\n' "$altered_preserved" "$disappearing_pid" >"$runtime_dir/caffeine-pids"
+printf 'disappear\n' >"$runtime_dir/caffeine-mode"
+rm -f "$runtime_dir/caffeine-list-count"
+invoke_repair panama.caffeine
+[[ "$repair_status" == 1 ]] || fail 'disappeared inhibitor PID was not safely refused'
+assert_repair_result panama.caffeine true 1
+wait "$disappearance_controller"
+kill -0 "$unrelated_pid" >/dev/null 2>&1 || fail 'PID disappearance signaled an unrelated process'
+
+# Rejected IDs are complete JSON, exit 2, and cause neither a process launch
+# nor a filesystem mutation.
+fixture_state() {
+    /usr/bin/python3 - "$fixture" <<'PY'
+import hashlib
+import os
+import stat
+import sys
+from pathlib import Path
+
+root = Path(sys.argv[1])
+digest = hashlib.sha256()
+for path in sorted(root.rglob("*"), key=lambda item: os.fsencode(str(item.relative_to(root)))):
+    relative = os.fsencode(str(path.relative_to(root)))
+    metadata = path.lstat()
+    digest.update(relative + b"\0" + oct(stat.S_IMODE(metadata.st_mode)).encode() + b"\0")
+    if path.is_symlink():
+        digest.update(b"link\0" + os.fsencode(os.readlink(path)) + b"\0")
+    elif path.is_file():
+        digest.update(b"file\0" + hashlib.sha256(path.read_bytes()).digest())
+    elif path.is_dir():
+        digest.update(b"dir\0")
+    else:
+        digest.update(b"other\0")
+print(digest.hexdigest())
+PY
+}
+for rejected_id in unknown.check integration.home-assistant input.brightness \
+    desktop.notifications ../../escape 'desktop.vicinae;touch injected'; do
+    : >"$repair_log"
+    before_state="$(fixture_state)"
+    invoke_repair "$rejected_id"
+    [[ "$repair_status" == 2 ]] || fail "$rejected_id returned $repair_status instead of 2"
+    assert_repair_result "$rejected_id" false 2
+    [[ ! -s "$repair_log" ]] || fail "$rejected_id launched a process"
+    [[ "$(fixture_state)" == "$before_state" ]] || fail "$rejected_id mutated the filesystem"
+done
+
+printf 'panama doctor contract: PASS\n'

tests/quickshell/power-profile-contract.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+
+# panama-power-profile reads and sets the system power profile.
+#
+# Runs against a stubbed busctl. The real daemon is a SYSTEM service shared with
+# everything else on the machine, and a test that flipped the daily driver into
+# power-saver and crashed before restoring would leave it there.
+#
+# The parsing is the fragile part. busctl renders the Profiles property flat:
+#
+#   v aa{sv} 3 2 "Profile" s "power-saver" "Driver" s "tuned" 2 "Profile" ...
+#
+# so profile names and driver names sit in the same stream. A pattern loose
+# enough to match both reports the driver as an extra profile -- and on this
+# machine the driver is literally called "tuned", which reads exactly like a
+# plausible fourth profile.
+
+set -uo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+helper="$repo_dir/config/dot/quickshell/scripts/panama-power-profile"
+
+fail() {
+    printf 'power profile contract: %s\n' "$1" >&2
+    exit 1
+}
+
+stub_dir="$(mktemp -d /tmp/panama-power.XXXXXX)"
+trap 'rm -rf "$stub_dir"' EXIT
+
+cat >"$stub_dir/busctl" <<'STUB'
+#!/usr/bin/env bash
+# Records set-property calls so the test can assert what was written.
+case "${1:-}" in
+    status)
+        [[ "${PANAMA_POWER_FAKE:-up}" == "down" ]] && exit 1
+        exit 0 ;;
+    get-property)
+        case "${5:-}" in
+            ActiveProfile)       printf 's "performance"\n' ;;
+            PerformanceDegraded) printf 's "%s"\n' "${PANAMA_POWER_DEGRADED:-}" ;;
+            Profiles)
+                if [[ "${PANAMA_POWER_FAKE:-up}" == "empty" ]]; then
+                    printf 'v aa{sv} 0\n'
+                else
+                    printf 'v aa{sv} 3 2 "Profile" s "power-saver" "Driver" s "tuned" 2 "Profile" s "balanced" "Driver" s "tuned" 2 "Profile" s "performance" "Driver" s "tuned"\n'
+                fi ;;
+        esac
+        exit 0 ;;
+    set-property)
+        printf '%s\n' "${!#}" >>"$PANAMA_POWER_SET_LOG"
+        exit 0 ;;
+esac
+exit 0
+STUB
+chmod +x "$stub_dir/busctl"
+
+export PANAMA_POWER_SET_LOG="$stub_dir/sets.log"
+: >"$PANAMA_POWER_SET_LOG"
+
+run() { PATH="$stub_dir:$PATH" "$helper" "$@"; }
+
+# ── Parsing ──────────────────────────────────────────────────────────────────
+out="$(run list)"
+jq -e . >/dev/null 2>&1 <<<"$out" || fail "list did not emit JSON: $out"
+
+[[ "$(jq -r '.profiles | length' <<<"$out")" == "3" ]] \
+    || fail "expected exactly three profiles; a fourth usually means the Driver value was parsed as one: $out"
+
+jq -e '.profiles == ["power-saver", "balanced", "performance"]' >/dev/null <<<"$out" \
+    || fail "profiles were parsed wrongly or reordered: $out"
+
+jq -e '.profiles | index("tuned") == null' >/dev/null <<<"$out" \
+    || fail 'the driver name "tuned" was reported as a profile'
+
+[[ "$(jq -r '.active' <<<"$out")" == "performance" ]] \
+    || fail "the active profile was not read: $out"
+
+# ── Degradation is surfaced, since it makes the active profile a lie ─────────
+out="$(PANAMA_POWER_DEGRADED="lap-detected" run list)"
+[[ "$(jq -r '.degraded' <<<"$out")" == "lap-detected" ]] \
+    || fail "a degraded performance state was not reported: $out"
+
+# ── Setting ──────────────────────────────────────────────────────────────────
+run set balanced
+[[ "$(tail -1 "$PANAMA_POWER_SET_LOG")" == "balanced" ]] \
+    || fail "set did not write the requested profile: $(cat "$PANAMA_POWER_SET_LOG")"
+
+before="$(wc -l <"$PANAMA_POWER_SET_LOG")"
+run set 'evil; rm -rf /' 2>/dev/null
+[[ "$(wc -l <"$PANAMA_POWER_SET_LOG")" == "$before" ]] \
+    || fail 'a profile name with shell metacharacters reached the system service'
+
+# ── No daemon, and a daemon with nothing to offer, are both states ───────────
+out="$(PANAMA_POWER_FAKE=down run list)"
+jq -e '.profiles == [] and .error != ""' >/dev/null <<<"$out" \
+    || fail "a missing power daemon must be reported with a reason: $out"
+
+out="$(PANAMA_POWER_FAKE=empty run list)"
+jq -e '.profiles == [] and .error != ""' >/dev/null <<<"$out" \
+    || fail "a daemon offering no profiles must be reported, not shown as an empty card: $out"
+
+printf 'power profile contract: PASS\n'

tests/quickshell/settings-hyprland-write-contract.sh

@@ -137,10 +137,20 @@ last_error="$(qs_for_harness ipc call settings-system-test status | jq -r .lastE
 
 # ── A rejected value must be refused, not silently accepted ──────────────────
 qs_for_harness ipc call settings-system-test apply "$target_auto_hdr" 7 "$target_direct" >/dev/null
-sleep 0.3
+
+# The refusal is reported asynchronously, so wait for it rather than sleeping a
+# fixed 0.3s and hoping. That sleep made this fail roughly one run in three,
+# reporting "a rejected value did not surface an error" when the error simply
+# had not arrived yet -- which reads as a missing guard rather than a slow one.
+rejected=""
+for _ in $(seq 1 60); do
+    rejected="$(qs_for_harness ipc call settings-system-test status | jq -r .lastError)"
+    [[ -n "$rejected" ]] && break
+    sleep 0.1
+done
+
 [[ "$(read_option misc:vrr)" == "$target_vrr" ]] || fail 'an out-of-allow-list VRR value reached the compositor'
-[[ -n "$(qs_for_harness ipc call settings-system-test status | jq -r .lastError)" ]] \
+[[ -n "$rejected" ]] || fail 'a rejected VRR value did not surface an error'
-    || fail 'a rejected VRR value did not surface an error'
 
 # ── Every getoption answer shape must be handled, not just integers ──────────
 # The compositor reports each option in a different JSON field depending on its

tests/quickshell/settings-pages-contract.sh

@@ -9,7 +9,7 @@ fail() {
     exit 1
 }
 
-pages=(Home Displays Connectivity Sound Notifications ScreenIntelligence Services About)
+pages=(Home Displays Connectivity Sound Notifications ScreenIntelligence Health About)
 for page in "${pages[@]}"; do
     page_file="$repo_dir/config/dot/quickshell/modules/settings/${page}Page.qml"
     [[ -f "$page_file" ]] || fail "${page}Page.qml is missing"
@@ -85,8 +85,13 @@ fi
 state_home="$(mktemp -d /tmp/panama-settings-pages-state.XXXXXX)"
 source_config_path="$repo_dir/config/dot/quickshell"
 config_path="$state_home/quickshell"
+harness="$config_path/settings-pages-harness.qml"
 test_bin="$state_home/bin"
 shell_log="$state_home/quickshell.log"
+production_config_path="$HOME/.config/quickshell/shell.qml"
+harness_pid=""
+harness_shell_id=""
+production_before=""
 
 cleanup_bootstrap() {
     rm -rf "$state_home"
@@ -95,6 +100,21 @@ trap cleanup_bootstrap EXIT
 
 mkdir -p "$test_bin"
 cp -a "$source_config_path" "$config_path"
+python3 - "$config_path/shell.qml" "$harness" "$$" <<'PY'
+import sys
+
+source_path, harness_path, identity = sys.argv[1:]
+source = open(source_path, encoding="utf-8").read()
+needle = "ShellRoot {\n"
+replacement = (
+    needle
+    + f'    readonly property string settingsPagesHarnessIdentity: "settings-pages-contract-{identity}"\n'
+)
+if source.count(needle) != 1:
+    raise SystemExit("shell.qml does not have exactly one ShellRoot")
+with open(harness_path, "w", encoding="utf-8") as handle:
+    handle.write(source.replace(needle, replacement, 1))
+PY
 
 cat >"$config_path/scripts/panama-home-assistant" <<'EOF'
 #!/usr/bin/env bash
@@ -138,52 +158,141 @@ EOF
 chmod +x "$test_bin/flatpak"
 
 qs_for_test() {
-    PATH="$test_bin:$PATH" QS_CONFIG_PATH="$config_path" XDG_STATE_HOME="$state_home" \
+    if [[ "${1:-}" == "ipc" && "$harness_pid" =~ ^[0-9]+$ ]]; then
-        qs -p "$config_path" "$@"
+        PATH="$test_bin:$PATH" XDG_STATE_HOME="$state_home" \
+            qs -p "$harness" ipc --pid "$harness_pid" "${@:2}"
+    else
+        PATH="$test_bin:$PATH" XDG_STATE_HOME="$state_home" \
+            qs -p "$harness" "$@"
+    fi
 }
 
-stop_test_shell() {
+instances_for_path() {
-    qs_for_test kill >/dev/null 2>&1 || true
+    local expected_path="$1" listing
-    for _ in $(seq 1 80); do
+
-        if ! qs_for_test list 2>/dev/null | rg '^Instance ' >/dev/null \
+    listing="$(qs list --all 2>/dev/null)" || return 1
-                && ! qs_for_test ipc show >/dev/null 2>&1; then
+    awk -v expected="$expected_path" '
-            return 0
+        /^Instance / { pid = ""; shell_id = "" }
+        /^[[:space:]]*Process ID:/ { pid = $3 }
+        /^[[:space:]]*Shell ID:/ { shell_id = $3 }
+        /^[[:space:]]*Config path:/ {
+            path = $0
+            sub(/^[[:space:]]*Config path: /, "", path)
+            if (path == expected && pid ~ /^[0-9]+$/ && shell_id != "")
+                print pid "|" shell_id
+        }
+    ' <<<"$listing"
+}
+
+harness_identity_matches() {
+    local current
+
+    [[ "$harness_pid" =~ ^[0-9]+$ && -n "$harness_shell_id" ]] || return 1
+    current="$(instances_for_path "$harness")" || return 1
+    grep -Fxq "$harness_pid|$harness_shell_id" <<<"$current"
+}
+
+production_is_preserved() {
+    local current record pid shell_id
+
+    current="$(instances_for_path "$production_config_path")" || return 1
+    while IFS='|' read -r pid shell_id; do
+        [[ -n "$pid" ]] || continue
+        kill -0 "$pid" >/dev/null 2>&1 || return 1
+        record="$pid|$shell_id"
+        grep -Fxq "$record" <<<"$current" || return 1
+    done <<<"$production_before"
+}
+
+stop_harness() {
+    local remaining
+
+    if harness_identity_matches; then
+        kill "$harness_pid" >/dev/null 2>&1 || true
+        for _ in $(seq 1 80); do
+            ! kill -0 "$harness_pid" >/dev/null 2>&1 && break
+            sleep 0.05
+        done
+        if kill -0 "$harness_pid" >/dev/null 2>&1 && harness_identity_matches; then
+            kill -KILL "$harness_pid" >/dev/null 2>&1 || true
+            for _ in $(seq 1 20); do
+                ! kill -0 "$harness_pid" >/dev/null 2>&1 && break
+                sleep 0.05
+            done
         fi
-        sleep 0.1
+    fi
-    done
+    remaining="$(instances_for_path "$harness")" || return 1
-    return 1
+    harness_pid=""
+    harness_shell_id=""
+    [[ -z "$remaining" ]]
 }
 
 cleanup() {
-    qs_for_test ipc call settings close >/dev/null 2>&1 || true
+    local cleanup_ok=0
-    if stop_test_shell; then
+
+    stop_harness || cleanup_ok=1
+    production_is_preserved || cleanup_ok=1
+    if (( cleanup_ok == 0 )); then
         rm -rf "$state_home"
     else
-        printf 'settings pages contract: branch shell did not stop; retained %s\n' \
+        printf 'settings pages contract: isolated harness cleanup failed; retained %s\n' \
             "$state_home" >&2
     fi
+    return "$cleanup_ok"
 }
 trap cleanup EXIT
 
 start_test_shell() {
-    stop_test_shell || fail 'pre-existing branch shell did not stop cleanly'
+    local harness_instances production_pid production_shell_id
+
+    harness_instances="$(instances_for_path "$harness")" \
+        || fail 'could not inspect Quickshell instances before starting the runtime harness'
+    [[ -z "$harness_instances" ]] \
+        || fail 'an unexpected process already uses the runtime harness path'
     for _attempt in 1 2; do
         qs_for_test --daemonize >"$shell_log" 2>&1
         for _ in $(seq 1 80); do
-            if qs_for_test ipc show 2>/dev/null | rg '^target settings$' >/dev/null; then
+            harness_instances="$(instances_for_path "$harness")" \
-                return
+                || fail 'could not inspect the runtime harness instance'
-            fi
+            [[ -n "$harness_instances" ]] && break
-            sleep 0.1
+            sleep 0.05
         done
-        stop_test_shell || fail 'failed branch-shell attempt did not stop cleanly'
+        if [[ "$(wc -l <<<"$harness_instances")" == 1 && -n "$harness_instances" ]]; then
+            IFS='|' read -r harness_pid harness_shell_id <<<"$harness_instances"
+            [[ "$harness_pid" =~ ^[0-9]+$ ]] \
+                || fail 'runtime harness did not expose a numeric PID'
+
+            while IFS='|' read -r production_pid production_shell_id; do
+                [[ -n "$production_pid" ]] || continue
+                [[ "$harness_shell_id" != "$production_shell_id" ]] || {
+                    stop_harness
+                    fail 'runtime harness shares a Shell ID with production'
+                }
+            done <<<"$production_before"
+            production_is_preserved || {
+                stop_harness
+                fail 'production changed before isolated page routing began'
+            }
+
+            for _ in $(seq 1 80); do
+                if qs_for_test ipc show 2>/dev/null | rg '^target settings$' >/dev/null; then
+                    return
+                fi
+                sleep 0.1
+            done
+        fi
+        stop_harness || fail 'failed runtime harness attempt did not stop cleanly'
     done
     sed -n '1,200p' "$shell_log" >&2
     fail 'isolated branch shell did not start'
 }
 
+production_before="$(instances_for_path "$production_config_path")" \
+    || fail 'could not list Quickshell instances for the production baseline'
+production_is_preserved || fail 'could not capture a stable production instance set'
 start_test_shell
 qs_for_test ipc call home-assistant fixture ready >/dev/null
-shell_pid="$(qs_for_test list | awk '/Process ID:/ { print $3; exit }')"
+shell_pid="$harness_pid"
 [[ "$shell_pid" =~ ^[0-9]+$ ]] || fail 'could not identify the branch shell process'
 
 pages=(home appearance displays connectivity home-phone desktop sound notifications screen-intelligence shortcuts services about)
@@ -218,6 +327,8 @@ intelligence_desktop_file="$HOME/.local/share/applications/panama-screen-intelli
 desktop-file-validate "$intelligence_desktop_file" >/dev/null || fail 'Screen Intelligence desktop entry is invalid'
 
 trap - EXIT
-cleanup
+cleanup || fail 'runtime harness did not stop without disturbing production'
 [[ ! -e "$state_home" ]] || fail 'temporary Settings state was not removed after shell exit'
-printf 'settings pages contract: PASS\n'
+production_pids="$(cut -d'|' -f1 <<<"$production_before" | paste -sd, -)"
+[[ -n "$production_pids" ]] || production_pids="none"
+printf 'settings pages contract: PASS (production PIDs preserved: %s)\n' "$production_pids"

tests/quickshell/settings-search-contract.sh

@@ -58,8 +58,13 @@ wallpaper|Wallpaper|appearance
 blur|Blur|appearance
 timezone|Timezone|datetime
 repeat delay|Repeat delay|shortcuts
+system health|System Health|services
+doctor|Copy health report|services
 CASES
 
+! rg -Fq 'Startup & Services' "$repo_dir/config/dot/quickshell/services/SettingsSearch.qml" \
+    || fail 'search index still uses the retired Startup & Services name'
+
 # ── Shortcuts are searchable by what they do ─────────────────────────────────
 [[ "$(find_top screenshot | jq -r .topPage)" == "shortcuts" ]] \
     || fail 'searching a shortcut description did not route to the shortcuts page'

tests/quickshell/wifi-qr-contract.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+
+# panama-wifi-qr renders a saved network as a QR code a phone can scan.
+#
+# The QR contains the network PASSWORD in machine-readable form, so most of what
+# is worth testing here is about handling that safely rather than about QR
+# codes. Both nmcli and qrencode are stubbed: the real ones would read this
+# machine's actual passphrases, and a test that writes the daily driver's Wi-Fi
+# password into a fixture directory is not one worth having.
+
+set -uo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+helper="$repo_dir/config/dot/quickshell/scripts/panama-wifi-qr"
+
+fail() {
+    printf 'wifi qr contract: %s\n' "$1" >&2
+    exit 1
+}
+
+work="$(mktemp -d /tmp/panama-wifiqr.XXXXXX)"
+trap 'rm -rf "$work"' EXIT
+mkdir -p "$work/bin" "$work/run"
+
+readonly SECRET='hunter2-secret'
+
+cat >"$work/bin/nmcli" <<STUB
+#!/usr/bin/env bash
+# -t -f NAME,TYPE connection show
+if [[ "\$*" == *"-f NAME,TYPE"* ]]; then
+    printf 'home net:802-11-wireless\n'
+    printf 'work-eap:802-11-wireless\n'
+    printf 'Wired connection 1:802-3-ethernet\n'
+    exit 0
+fi
+name="\${@: -1}"
+case "\$*" in
+    *802-11-wireless.ssid*)
+        # An SSID containing reserved characters, to prove they are escaped.
+        case "\$name" in
+            "home net") printf 'home;net\n' ;;
+            "work-eap") printf 'work-eap\n' ;;
+        esac ;;
+    *802-11-wireless.hidden*) printf 'no\n' ;;
+    *802-11-wireless-security.psk*)
+        # work-eap is enterprise: no passphrase exists to share.
+        [[ "\$name" == "home net" ]] && printf '%s\n' "$SECRET" ;;
+esac
+exit 0
+STUB
+chmod +x "$work/bin/nmcli"
+
+# Records its argv and its stdin separately, so the test can prove the secret
+# arrived on stdin and never on the command line -- argv is world-readable
+# through /proc while a process runs.
+cat >"$work/bin/qrencode" <<'STUB'
+#!/usr/bin/env bash
+printf '%s\n' "$*" >>"$QRENCODE_ARGV_LOG"
+out=""
+prev=""
+for arg in "$@"; do
+    [[ "$prev" == "-o" ]] && out="$arg"
+    prev="$arg"
+done
+cat >"$QRENCODE_STDIN_LOG"
+printf 'fake-png' >"$out"
+exit 0
+STUB
+chmod +x "$work/bin/qrencode"
+
+export QRENCODE_ARGV_LOG="$work/argv.log"
+export QRENCODE_STDIN_LOG="$work/stdin.log"
+: >"$QRENCODE_ARGV_LOG"
+: >"$QRENCODE_STDIN_LOG"
+
+run() { PATH="$work/bin:$PATH" XDG_RUNTIME_DIR="$work/run" "$helper" "$@"; }
+
+# ── Listing distinguishes shareable from not ────────────────────────────────
+out="$(run list)"
+jq -e . >/dev/null 2>&1 <<<"$out" || fail "list did not emit JSON: $out"
+[[ "$(jq -r '.networks | length' <<<"$out")" == "2" ]] \
+    || fail "only wireless connections belong in the list: $out"
+jq -e '.networks[] | select(.name == "home net") | .shareable == true' >/dev/null <<<"$out" \
+    || fail "a network with a passphrase must be shareable: $out"
+jq -e '.networks[] | select(.name == "work-eap") | .shareable == false' >/dev/null <<<"$out" \
+    || fail "an enterprise network has no passphrase, so a QR code for it cannot work: $out"
+
+# ── The payload ─────────────────────────────────────────────────────────────
+path="$(run qr 'home net' | jq -r .path)"
+[[ -n "$path" && -e "$path" ]] || fail 'no image was produced'
+
+payload="$(cat "$QRENCODE_STDIN_LOG")"
+grep -q "P:$SECRET;" <<<"$payload" \
+    || fail 'the passphrase did not reach the payload intact'
+
+# The SSID is "home;net": unescaped, the semicolon ends the S: field early and
+# the code describes a different network.
+grep -qF 'S:home\;net;' <<<"$payload" \
+    || fail "a reserved character in the SSID was not escaped: $payload"
+
+[[ "$(wc -l <"$QRENCODE_STDIN_LOG")" == "0" ]] \
+    || fail "the payload contains a newline; nmcli's trailing newline must be stripped: $(cat -A "$QRENCODE_STDIN_LOG")"
+
+grep -q ';;$' <<<"$payload" || fail "the WIFI: URI must be terminated with ;;: $payload"
+
+# ── The secret must never appear in argv ────────────────────────────────────
+grep -q "$SECRET" "$QRENCODE_ARGV_LOG" \
+    && fail 'the passphrase was passed as a command-line argument, where /proc exposes it to every process on the machine'
+
+# ── The image and its directory must not be readable by others ──────────────
+[[ "$(stat -c '%a' "$path")" == "600" ]] \
+    || fail "the QR image is mode $(stat -c '%a' "$path"); it contains a password"
+[[ "$(stat -c '%a' "$(dirname "$path")")" == "700" ]] \
+    || fail "the directory holding QR images is mode $(stat -c '%a' "$(dirname "$path")")"
+
+# ── No temporary payload files may survive ──────────────────────────────────
+leftovers="$(find "$work/run" -name 'payload.*' | wc -l)"
+[[ "$leftovers" == "0" ]] \
+    || fail "$leftovers temporary payload file(s) containing the passphrase were left behind"
+
+# ── An unknown network is an error, not an empty image ──────────────────────
+out="$(run qr 'no-such-network')"
+jq -e '.path == "" and .error != ""' >/dev/null <<<"$out" \
+    || fail "an unknown network must be reported: $out"
+
+printf 'wifi qr contract: PASS\n'