Merge codex's System Health and recovery work

Brings in panama-doctor (a 25-check diagnostic with fixture-backed
contracts), a Health service, a System Health page replacing Startup &
Services, and a bar indicator that stays absent until something is
actually degraded. All seven of its contracts pass on the merge.

Three things needed resolving rather than accepting:

The branch predates the debranding, so its user-visible strings still
named the product -- "Panama desktop is healthy", "Restart Panama",
"Panama tools". Rewritten to say the same thing without the name, which
is what the rest of the app now does.

Its Fedora hand-off card was a single button calling openGnomePanel
("network") under a subtitle naming five subjects. Main had already
replaced that with a row per subject, each opening the panel that owns
it, so those rows are ported into HealthPage instead. Printers and
online accounts stay on Network & Devices with the rest of the network
hardware.

That broke its own assertion, which matched the literal
openGnomePanel("network") string. Rewritten rather than reverted: it now
checks the boundary card exists and that every panel named in HealthPage
is one openGnomePanel actually allows, since a name outside the
allow-list opens nothing at all. Verified it catches a plausible-looking
wrong name.

SettingsShell and SettingsSidebar conflicted because both sides added
pages; resolved as the union, keeping its System Health page and live
footer alongside main's Mouse & Touchpad, Privacy & Security, Region &
Language and Online Accounts.

Claude-Session: https://claude.ai/code/session_01BRvzt4H8XXLPVH5MyYdk9L

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/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/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,423 @@
+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);
+        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)),
+            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: "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."
+
+        // One row per subject rather than a single "Open GNOME Settings"
+        // button. Naming five things and then opening the network panel
+        // regardless reads as a broken button rather than a deliberate
+        // hand-off, and left someone looking for printers 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/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/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)
-        border.width: 0
+        activeFocusOnTab: true
+        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,656 @@
+#!/usr/bin/env python3
+
+"""Redacted diagnostics and bounded repairs for Panama-owned functionality."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+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"]
+
+
+@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"
+    if source.is_dir() and installed.is_symlink() and installed.exists():
+        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.")
+    uid = str(os.getuid())
+    inhibitors = 0
+    malformed = False
+    for line in result.stdout.splitlines():
+        parts = line.split()
+        relevant = len(parts) >= 2 and parts[0] == "Panama" and parts[1] == uid and "Caffeine" in parts
+        if not relevant:
+            continue
+        if len(parts) >= 8 and parts[3].isdecimal() and parts[-2:] == ["Caffeine", "block"]:
+            inhibitors += 1
+        else:
+            malformed = True
+    if malformed:
+        return Check("panama.caffeine", "panama-tools", "Caffeine inhibitor", "warning", "Caffeine inhibitor probe returned an invalid result.")
+    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 repair_runtime_links(config: DoctorConfig) -> RepairResult:
+    sources = [(name, 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.")
+
+    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():
+                if destination.resolve(strict=False) == source.resolve(strict=True):
+                    continue
+                destination.unlink()
+                destination.symlink_to(source, target_is_directory=True)
+            elif destination.exists():
+                # A regular file or directory is user-owned unless proven
+                # otherwise. Report it, but never replace it.
+                blocked = True
+            else:
+                destination.symlink_to(source, target_is_directory=True)
+        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 file or directory is blocking a Panama runtime 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 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_pids: list[str] = []
+    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:
+            return RepairResult("panama.caffeine", True, 1, "Caffeine inhibitor metadata was invalid; nothing was released.")
+        if parts[6] != "Caffeine" or parts[7] != "block":
+            continue
+        if not parts[3].isdecimal():
+            return RepairResult("panama.caffeine", True, 1, "Caffeine inhibitor metadata was invalid; nothing was released.")
+        inhibitor_pids.append(parts[3])
+
+    if len(inhibitor_pids) <= 1:
+        return RepairResult("panama.caffeine", True, 0, "No duplicate Panama Caffeine inhibitors needed release.")
+
+    for pid in inhibitor_pids[1:]:
+        exit_code, _ = run_repair_command(("kill", "--", pid), config)
+        if exit_code != 0:
+            return RepairResult("panama.caffeine", True, exit_code, "A duplicate Panama Caffeine inhibitor could not be released.")
+    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/services/Health.qml

@@ -0,0 +1,440 @@
+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 (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;
+
+        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/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/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/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,568 @@
+# 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, live read-only audit, and documentation
+
+**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, a redacted live health snapshot, and final verification evidence.
+
+- [ ] **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; Quickshell tests report 58 contracts after the three new contracts land.
+
+- [ ] **Step 3: Run a redacted live read-only comparison**
+
+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: Reload and inspect the live 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.

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,265 @@
+#!/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)"
+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}}]}'
+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 "$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)"
+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"
+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" && "$2" == "panama.caffeine" && "$3" == "--json" ]]; then' \
+    '    sleep 0.25' \
+    '    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' \
+    '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" qs -p "$harness" "$@"
+}
+harness_pid=""
+
+cleanup() {
+    [[ -n "$harness_pid" ]] && kill "$harness_pid" >/dev/null 2>&1 || true
+    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" \
+    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 }')"
+
+[[ "$(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"
+repair_generation="$(jq -r .generation <<<"$state")"
+[[ "$(run ipc call health-test repair panama.caffeine)" == "true" ]] \
+    || fail 'repairable check was refused'
+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"
+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"
+
+[[ "$(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 "$mismatch_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,415 @@
+#!/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'
+# The Fedora hand-off is a row per subject, not one button that opened the
+# network panel whatever it was labelled. What matters is that each row reaches
+# the panel that owns it, so this checks the boundary still exists and that
+# every panel it names is one openGnomePanel accepts -- a name outside that
+# allow-list opens nothing and reports an error, i.e. a dead button.
+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 .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/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-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,431 @@
+#!/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)"
+trap 'rm -rf "$fixture"' 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"
+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"
+
+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"
+
+# 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="$fixture/repair-root"
+repair_log="$runtime_dir/repair.log"
+mkdir -p "$repair_root/config/dot" "$repair_root/setup/scripts"
+for name in hypr quickshell uwsm vicinae; do
+    mkdir -p "$repair_root/config/dot/$name"
+done
+
+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/kill" <<'EOF'
+#!/usr/bin/bash
+set -euo pipefail
+printf 'kill' >>"$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"
+uid="$(/usr/bin/id -u)"
+printf 'Panama %s fixture-user 4101 systemd-inhibit sleep:idle Caffeine block\n' "$uid"
+printf 'Panama %s fixture-user 4102 systemd-inhibit sleep:idle Caffeine block\n' "$uid"
+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
+
+cat >"$repair_root/setup/scripts/link-vicinae-scripts" <<'EOF'
+#!/usr/bin/bash
+set -euo pipefail
+printf 'link-vicinae-scripts|%s' "$0" >>"$XDG_RUNTIME_DIR/repair.log"
+if (( $# > 0 )); then
+    printf '|%s' "$@" >>"$XDG_RUNTIME_DIR/repair.log"
+fi
+printf '\n' >>"$XDG_RUNTIME_DIR/repair.log"
+EOF
+chmod +x "$bin_dir/systemctl" "$bin_dir/panama-action" "$bin_dir/kill" \
+    "$bin_dir/systemd-inhibit" "$repair_root/setup/scripts/link-vicinae-scripts"
+
+run_repair() {
+    HOME="$home" \
+    PATH="$bin_dir" \
+    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" \
+    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 Vicinae repair executes only the authored setup helper with no arguments.
+: >"$repair_log"
+invoke_repair panama.vicinae-commands
+[[ "$repair_status" == 0 ]] || fail "Vicinae command repair returned $repair_status"
+assert_repair_result panama.vicinae-commands true 0
+[[ "$(<"$repair_log")" == "link-vicinae-scripts|$repair_root/setup/scripts/link-vicinae-scripts" ]] \
+    || fail "Vicinae command repair argv was not exact: $(<"$repair_log")"
+
+# Runtime-link repair may replace only the four authored symlink names. Broken
+# or absent links are recreated toward authored tracked destinations; regular
+# files and directories remain untouched and make the result incomplete.
+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 "$fixture/missing-hypr" "$config_home/hypr"
+ln -s "$fixture/missing-quickshell" "$config_home/quickshell"
+printf 'user-owned file\n' >"$config_home/uwsm"
+mkdir "$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 'hypr link was not recreated toward its authored destination'
+[[ -L "$config_home/quickshell" && "$(readlink "$config_home/quickshell")" == "$repair_root/config/dot/quickshell" ]] \
+    || fail 'quickshell link was not recreated toward its authored destination'
+[[ -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'
+[[ -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'
+
+# Caffeine repair parses exact authored metadata, keeps the first valid lock,
+# and releases only later exact matches.
+: >"$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\nkill|--|4102'
+[[ "$(<"$repair_log")" == "$expected_caffeine" ]] \
+    || fail "Caffeine repair did not preserve/filter exact inhibitors: $(<"$repair_log")"
+
+# Rejected IDs are complete JSON, exit 2, and cause neither a process launch
+# nor a filesystem mutation.
+fixture_state() {
+    find "$config_home" -mindepth 1 -printf '%P|%y|%l\n' | sort | sha256sum | awk '{print $1}'
+}
+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/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"

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'