shells: a settings page that restarts the shells, with a notification

Settings > Desktop > Shells lists every directory holding a shell.qml,
running or stopped by `qs list --all`, with Restart (Start when it is not
running) per row and a Restart all. Every button runs reload.sh through
Quickshell.execDetached, which leaves the script outside the desktop
shell's process, so restarting desktop from its own settings window
works: the window closes and the new process carries on.

restart.sh wraps reload.sh and sends one notification naming the shells
that came back, or a critical one naming those that did not. Back means
qs lists an instance on the shell's config path under a pid it did not
have before, within 5s; the old instance can linger in the list for a
moment after qs kill. It checks the process, not the config, so a shell
that starts with a broken component still counts as back.

The rows reuse the ai module's AiRow rather than a copy of it.

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

4 files changed, 208 insertions, 0 deletions

diff --git a/desktop/modules/shells/README.md b/desktop/modules/shells/README.md
new file mode 100644
index 0000000..16a93b5
--- /dev/null
+++ b/desktop/modules/shells/README.md
@@ -0,0 +1,21 @@
+# shells
+
+Every directory in the repo holding a `shell.qml`, with whether `qs list
+--all` shows an instance on it, and a Restart (or Start, when it is not
+running) per row plus a Restart all. All three run `reload.sh`, so a button
+does what the script does from a terminal, wrapped by `restart.sh`, which
+then sends one notification naming the shells that came back, or a critical
+one naming those that did not. Back means a `qs` instance on the shell's
+config path under a pid it did not have before, within 5s: the old instance
+can linger in the list for a moment after `qs kill`. It is the process, not
+the config: a shell that starts with a broken component counts as back.
+
+The script is started with `Quickshell.execDetached`, which leaves it outside
+the desktop shell's process: restarting `desktop` from here kills the process
+drawing the page and the script carries on and starts the new one. The
+settings window closes with it and is not reopened. The new shell inherits
+the desktop shell's environment, which is the one Hyprland's autostart gave
+it.
+
+A hung desktop shell cannot be restarted from here, since the page is part of
+it. `./reload.sh` from a terminal remains the way out.
diff --git a/desktop/modules/shells/ShellsModule.qml b/desktop/modules/shells/ShellsModule.qml
new file mode 100644
index 0000000..1a747ac
--- /dev/null
+++ b/desktop/modules/shells/ShellsModule.qml
@@ -0,0 +1,80 @@
+// Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License version 2 as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+import Quickshell
+import Quickshell.Io
+import QtQuick
+import "../.."
+
+// Every shell in the repo, running or not, with a restart through reload.sh,
+// wrapped by restart.sh, which notifies once the shells are back. Started
+// detached, so it outlives the qs that started it:
+// restarting the desktop shell from its own settings window works, the
+// window just closes until the new process is up.
+Module {
+    id: sm
+    name: "shells"
+    label: "Shells"
+    // nf-fa-refresh, present in Inconsolata Nerd Font.
+    icon: ""
+    settings: true
+    group: "Desktop"
+    keywords: ["restart", "reload", "quickshell", "qs", "process", "start"]
+
+    readonly property string root: Quickshell.shellDir + "/.."
+    // [{name, running}], one per directory holding a shell.qml.
+    property var shells: []
+
+    // An empty name restarts every shell the page lists.
+    function restart(name) {
+        Quickshell.execDetached(["sh", Quickshell.shellDir + "/modules/shells/restart.sh", sm.root]
+            .concat(name ? [name] : sm.shells.map(s => s.name)));
+        repoll.restart();
+    }
+
+    function refresh() {
+        proc.rows = [];
+        proc.running = false;
+        proc.running = true;
+    }
+
+    // reload.sh waits a second before it returns; read the list after that.
+    property Timer repoll: Timer {
+        interval: 2000
+        onTriggered: sm.refresh()
+    }
+
+    // A shell is running when qs lists an instance on its config path.
+    property Process proc: Process {
+        property var rows: []
+        command: ["sh", "-c", 'cd "$1" || exit 1; up=$(qs list --all 2>/dev/null); '
+            + 'for f in */shell.qml; do case "$up" in '
+            + '*"Config path: $PWD/$f"*) s=running ;; *) s=stopped ;; esac; '
+            + 'printf "%s\\t%s\\n" "${f%/shell.qml}" "$s"; done', "sh", sm.root]
+        stdout: SplitParser {
+            onRead: line => {
+                const f = line.split("\t");
+                if (f.length === 2) proc.rows.push({ name: f[0], running: f[1] === "running" });
+            }
+        }
+        onExited: {
+            sm.shells = proc.rows;
+            sm.searchItems = proc.rows.map(s => ({ text: s.name, key: "shell:" + s.name }));
+        }
+    }
+
+    page: Component {
+        Page {
+            title: "Shells"
+            ShellsPage { width: parent.width; shells: sm }
+        }
+    }
+}
diff --git a/desktop/modules/shells/ShellsPage.qml b/desktop/modules/shells/ShellsPage.qml
new file mode 100644
index 0000000..abbb2b1
--- /dev/null
+++ b/desktop/modules/shells/ShellsPage.qml
@@ -0,0 +1,51 @@
+// Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License version 2 as
+// published by the Free Software Foundation.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+
+import QtQuick
+import "../.."
+import "../ai"
+
+// One row per shell, Restart when it runs and Start when it does not, both
+// through reload.sh. The desktop row restarts the process drawing this page.
+Column {
+    id: page
+
+    required property var shells
+
+    spacing: 8
+
+    Component.onCompleted: page.shells.refresh()
+
+    AiRow {
+        width: page.width
+        title: "All shells"
+        detail: "Restarts every one, this window included"
+        on: true
+        action: "Restart all"
+        onTriggered: page.shells.restart("")
+    }
+
+    Repeater {
+        model: page.shells.shells
+
+        AiRow {
+            required property var modelData
+            objectName: "shell:" + modelData.name
+            width: page.width
+            title: modelData.name
+            on: modelData.running
+            detail: (modelData.running ? "Running" : "Stopped")
+                + (modelData.name === "desktop" ? " · hosts this window" : "")
+            action: modelData.running ? "Restart" : "Start"
+            onTriggered: page.shells.restart(modelData.name)
+        }
+    }
+}
diff --git a/desktop/modules/shells/restart.sh b/desktop/modules/shells/restart.sh
new file mode 100755
index 0000000..2975d41
--- /dev/null
+++ b/desktop/modules/shells/restart.sh
@@ -0,0 +1,56 @@
+#!/bin/sh
+#
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+
+# restart.sh <repo> <shell>...: reload.sh on the named shells, then one
+# notification saying which came back. A shell came back when qs lists an
+# instance on its config path under a pid it did not have before, within 5s:
+# the old instance can still be listed for a moment after qs kill, and a
+# config that fails to load exits rather than lingering.
+#
+# ponytail: "came back" is the process, not the config. A shell that loads
+# with a broken component still counts; its log says so.
+
+root=$(cd "$1" && pwd) || exit 1
+shift
+
+# The pids qs lists for <shell>'s config path, one per line.
+pids() {
+    qs list --all 2>/dev/null | awk -v p="Config path: $root/$1/shell.qml" '
+        /Process ID:/ { id = $3 } index($0, p) { print id }'
+}
+
+old=""
+for n; do old="$old $(pids "$n")"; done
+
+"$root/reload.sh" "$@" >/dev/null 2>&1
+
+good=""
+bad=""
+for n; do
+    back=""
+    for _ in 1 2 3 4 5 6 7 8 9 10; do
+        for p in $(pids "$n"); do
+            case " $old " in *" $p "*) ;; *) back=1 ;; esac
+        done
+        [ -n "$back" ] && break
+        sleep 0.5
+    done
+    if [ -n "$back" ]; then good="$good $n"; else bad="$bad $n"; fi
+done
+
+if [ -n "$bad" ]; then
+    notify-send --app-name=Keystone --urgency=critical --icon=dialog-error \
+        "Shells" "Did not come back:$bad${good:+. Restarted:$good}"
+else
+    notify-send --app-name=Keystone --icon=dialog-information "Shells" "Restarted:$good"
+fi