path: root/docs/superpowers/plans/2026-09-15-status-registry.md

# Status Registry 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:** A `status` singleton and drawer module owning desktop modes (`dnd`, `presentation`) as files in `$XDG_RUNTIME_DIR`, with a `statusctl` CLI so anything on the system can read, set and watch them.

**Architecture:** One `pragma Singleton` in `shared/Status.qml`, symlinked into `desktop/`, holding a `FileView` per mode with `atomicWrites` and `watchChanges` set explicitly. Modes are booleans; `presentation` additionally asserts an `IdleInhibitor`, pauses breaktimer through a `Process`, and drives `dnd` while recording the prior value. A thin drawer module renders a tile and a page over the singleton. `~/bin/statusctl` reads and writes the same files directly, so it works when the shell is down.

**Tech Stack:** Quickshell 0.3.1, Qt6 QML, `Quickshell.Io.FileView`, `Quickshell.Wayland.IdleInhibitor`, bash, `inotifywait` (inotify-tools 4.23.9.0).

**Spec:** `docs/superpowers/specs/2026-09-15-status-registry-design.md`

---

## Global Constraints

- Quickshell 0.3.1, Qt6 QML. Run configs with `qs -p ./desktop`. The running process is `qs`: `pkill -x qs`, `pgrep -cx qs`, never `pkill -f` (it kills the calling shell).
- GPLv2 only. Every new `.qml` file begins with this exact header, no exceptions:

```qml
// 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.
```

Shell scripts use the same notice with `#` comment markers, after the shebang.

- Module files live under `desktop/modules/status/` and reference root types (`Module`, `Page`, `Switch`, `Theme`), so each uses `import "../.."`.
- Inject the module into its tile and page under a short name, never `mod`. A component property named the same as the enclosing object's `id` binds to itself and arrives undefined. This module uses `st`.
- Reusing a `Process` needs `running = false` immediately before `running = true`.
- No em dashes anywhere. No home paths in committed files; `~` in documentation only. Nerd Font glyphs are written as `\uXXXX` in QML and their bytes verified with `git diff`.
- Every glyph must exist in Inconsolata Nerd Font and mean what it says. Check the font cmap rather than trusting a codepoint.
- Smoke-check command, harness owns the process and the log is read, never a later `pgrep`:

```bash
timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean"
```

Expected: `clean`. This briefly starts a second drawer instance; it dies with the timeout.

## Verified Facts (probed on this machine, 2026-09-15)

Do not re-probe these; they are measured, not assumed.

- `$XDG_RUNTIME_DIR` is `/run/user/1000`, a tmpfs (`mode=700,uid=1000` in `/proc/mounts`). A reboot clears it.
- `elogind` runs here (PID present, `pam_elogind.so` in the PAM stack for `login`, `sddm`, `xdm`, `kde`, `loginctl list-sessions` shows a tracked session on seat0). `man 8 pam_elogind` documents removing the runtime directory at last logout but also says the module no-ops when the system was not booted with elogind as init, which on Slackware it is not. Do not claim logout clears the files.
- The compositor advertises `zwp_idle_inhibit_manager_v1` version 1 (`wayland-info`). waybar's built-in `idle_inhibitor` already drives it, so hypridle honours the Wayland path. No D-Bus inhibit needed.
- `inotifywait` is `/usr/bin/inotifywait`, version 4.23.9.0.
- No `statusctl` or `notifyctl` on PATH, no `status.*` in the runtime directory, no colliding names in `~/bin`.
- `breaktimer.sh` accepts `start stop pause resume toggle status`, keeps `running|paused` in `$XDG_RUNTIME_DIR/breaktimer.state`, and is autostarted from `autostart.lua`. The registry must never write that file, only call the verbs.
- `Theme` carries `base surface text subtext red green yellow surfaceAlt overlay accent`, plus `fontFamily`, `fontSize` (16) and `iconFamily`.
- Inconsolata Nerd Font lives in `~/.fonts/i/InconsolataNerdFont-Regular.ttf`, not under
  `/usr/share/fonts` or `~/.local/share/fonts`. A cmap search that misses `~/.fonts` reports
  every codepoint absent, which reads as a missing glyph rather than a bad search. The font
  carries 11326 codepoints and `\uf205` is among them, confirmed with fontTools.
- The keepalive `PanelWindow` in `desktop/shell.qml` currently has **no `id`**. Task 3 adds one; `IdleInhibitor.window` needs a non-null reference.

## Unverified, confirm during implementation

Two claims come from the documentation and have not been observed running. Record what actually happens in the task report, and add an `AGENTS.md` trap in Task 8 for whichever bites.

- `FileView` with `watchChanges: true` is documented to fire `fileChanged` on its own `setText()`. If so, the singleton sees its own writes and must not re-enter. Task 1 handles this with a value comparison rather than a re-entrancy flag; confirm the comparison is actually needed.
- `IdleInhibitor` is documented to need a non-null `window` to do anything. Confirm that assigning the keepalive window is sufficient and that `hyprctl clients` count changes.

---

## File Structure

| file | responsibility |
|---|---|
| `shared/Status.qml` (create) | The singleton. Mode files, read/write, effects, the DND restore rule. |
| `desktop/Status.qml` (create, symlink) | Resolves the singleton for the drawer, matching `Theme.qml`. |
| `desktop/shell.qml` (modify) | Give the keepalive window an `id`; register `StatusModule`. |
| `desktop/modules/status/StatusModule.qml` (create) | Registration, tile and page components. |
| `desktop/modules/status/StatusTile.qml` (create) | Active mode count as the tile state line. |
| `desktop/modules/status/StatusPage.qml` (create) | One row per mode with a `Switch`. |
| `desktop/modules/status/StatusRow.qml` (create) | One mode row: label, description, switch. |
| `desktop/modules/status/README.md` (create) | Module notes, per repo convention. |
| `~/bin/statusctl` (create, outside repo) | CLI: get, set, toggle, watch. |
| `desktop/modules/status/statusctl` (create) | The tracked copy of the CLI, installed to `~/bin` by the user. |
| `desktop/modules/status/test-statusctl.sh` (create) | The one runnable check. |

`statusctl` lives in the repo and is copied to `~/bin` by the user, the same arrangement as `mail-notify.sh` and `waybar-mail.sh` under `modules/mail/`.

---

### Task 1: The singleton, DND only

**Files:**
- Create: `shared/Status.qml`
- Create: `desktop/Status.qml` (symlink)

**Interfaces:**
- Consumes: `Quickshell.Io.FileView`.
- Produces: singleton `Status` with `readonly property bool dnd`, `function setMode(name, on)`, `function toggleMode(name)`, `readonly property int activeCount`. Tasks 2 through 6 use all of these.

- [ ] **Step 1: Write `shared/Status.qml` with the dnd mode only**

```qml
// 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.

pragma Singleton

import Quickshell
import Quickshell.Io
import QtQuick

// Desktop modes as state. One file per mode under $XDG_RUNTIME_DIR, holding
// "0" or "1"; a missing file means off. The runtime directory is tmpfs, so a
// reboot resets every mode with no cleanup code here.
//
// The files are the interface, not this singleton: statusctl reads and writes
// them directly so it works while the shell is down, and the FileView watch
// means an external write repaints the drawer with no polling.
Singleton {
    id: root

    readonly property string dir: Quickshell.env("XDG_RUNTIME_DIR") || "/tmp"

    readonly property bool dnd: dndFile.value

    // Number of modes currently on. The tile shows this.
    readonly property int activeCount: (root.dnd ? 1 : 0)

    function setMode(name, on) {
        if (name === "dnd") dndFile.write(on);
    }

    function toggleMode(name) {
        if (name === "dnd") dndFile.write(!root.dnd);
    }

    // One mode file. Reads "1" as true and anything else, including a missing
    // file, as false.
    component ModeFile: FileView {
        id: mf

        property bool value: false

        // FileView is documented to fire fileChanged on its own setText, so a
        // write would re-enter this handler. Comparing before assigning makes
        // that harmless: the reparse yields the value just written and the
        // binding does not change.
        function reparse() {
            const t = mf.text().trim();
            const v = (t === "1");
            if (v !== mf.value) mf.value = v;
        }

        function write(on) {
            const s = on ? "1\n" : "0\n";
            mf.value = on;
            mf.setText(s);
        }

        // Both are the documented defaults in 0.3.1, set explicitly because
        // the CLI depends on them: statusctl watches close_write,moved_to
        // precisely because an atomic write lands as a rename, so a future
        // release flipping this default would break the watcher silently.
        atomicWrites: true
        watchChanges: true
        printErrors: false
        onFileChanged: mf.reload()
        onLoaded: mf.reparse()
        // A missing file is the off state, not an error worth logging.
        onLoadFailed: mf.value = false
    }

    ModeFile { id: dndFile; path: root.dir + "/status.dnd" }
}
```

- [ ] **Step 2: Create the symlink**

```bash
ln -s ../shared/Status.qml desktop/Status.qml
ls -l desktop/Status.qml
```

Expected: `desktop/Status.qml -> ../shared/Status.qml`.

- [ ] **Step 3: Smoke check that the singleton parses**

```bash
timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean"
```

Expected: `clean`. The singleton is not referenced by anything yet, so this only proves it compiles when resolved.

- [ ] **Step 4: Commit**

```bash
git add shared/Status.qml desktop/Status.qml
git commit -m "feat(desktop): add the status singleton with the dnd mode

Modes live as files under XDG_RUNTIME_DIR, one per mode, holding 0 or 1,
with a missing file meaning off. That directory is tmpfs, so a reboot
resets every mode and no cleanup code is needed.

FileView covers both directions: atomicWrites for the write, watchChanges
for the watch, so an external writer repaints the drawer with no polling.
The documented behaviour is that a FileView fires its own fileChanged on
setText, so the reparse compares before assigning and a self-write is a
no-op rather than a loop."
```

---

### Task 2: The statusctl CLI

**Files:**
- Create: `desktop/modules/status/statusctl`
- Test: `desktop/modules/status/test-statusctl.sh`

**Interfaces:**
- Consumes: the file format from Task 1 (`0`/`1`, missing means off).
- Produces: `statusctl <mode> get|set|toggle|watch`. Task 7 installs it and wires waybar to `watch` and `toggle`.

- [ ] **Step 1: Write the failing test**

```bash
mkdir -p desktop/modules/status
cat > desktop/modules/status/test-statusctl.sh <<'SCRIPT'
#!/bin/bash
#
# 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.
#
# The one runnable check for statusctl. It points XDG_RUNTIME_DIR at a
# temporary directory, so nothing here touches the live modes.
#
# Usage: ./test-statusctl.sh   (exit 0 = all passed)

set -u

here="$(cd "$(dirname "$0")" && pwd)"
ctl="$here/statusctl"
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
export XDG_RUNTIME_DIR="$tmp"

pass=0
fail=0

check() {
    local label="$1" want="$2" got="$3"
    if [[ "$want" == "$got" ]]; then
        printf 'ok   %s\n' "$label"
        pass=$((pass + 1))
    else
        printf 'FAIL %s: want %q, got %q\n' "$label" "$want" "$got"
        fail=$((fail + 1))
    fi
}

# A mode with no file reads as off.
check "missing file reads 0" "0" "$("$ctl" dnd get)"

# set writes the file and get reads it back.
"$ctl" dnd set 1
check "set 1 writes the file" "1" "$(cat "$tmp/status.dnd" | tr -d '[:space:]')"
check "get after set 1" "1" "$("$ctl" dnd get)"

# toggle flips it.
"$ctl" dnd toggle
check "toggle from 1" "0" "$("$ctl" dnd get)"
"$ctl" dnd toggle
check "toggle from 0" "1" "$("$ctl" dnd get)"

# set 0 writes rather than removing, so a reader sees an explicit off.
"$ctl" dnd set 0
check "set 0 writes the file" "0" "$("$ctl" dnd get)"

# An unknown mode is an error, not a silent success: a typo must not look
# like a mode that is off.
"$ctl" nosuch get >/dev/null 2>&1
check "unknown mode exits non-zero" "1" "$?"

# watch prints a line on change, and the class reflects the value. The
# atomic write arrives as a rename, which is why the watch needs moved_to.
out="$tmp/watch.out"
"$ctl" presentation watch > "$out" 2>/dev/null &
watcher=$!
sleep 0.3
"$ctl" presentation set 1
sleep 0.5
kill "$watcher" 2>/dev/null
wait "$watcher" 2>/dev/null
check "watch reports activated" "1" "$(grep -c '"class": *"activated"' "$out")"

# A missing file is reported as down, distinct from a mode that is off.
rm -f "$tmp/status.presentation"
out2="$tmp/watch2.out"
"$ctl" presentation watch > "$out2" 2>/dev/null &
watcher2=$!
sleep 0.5
kill "$watcher2" 2>/dev/null
wait "$watcher2" 2>/dev/null
check "watch reports down when absent" "1" "$(grep -c '"class": *"down"' "$out2")"

printf '\n%d passed, %d failed\n' "$pass" "$fail"
[[ "$fail" -eq 0 ]]
SCRIPT
chmod +x desktop/modules/status/test-statusctl.sh
```

- [ ] **Step 2: Run it to verify it fails**

```bash
bash desktop/modules/status/test-statusctl.sh
```

Expected: every check fails, because `statusctl` does not exist. The first line reads `FAIL missing file reads 0`.

- [ ] **Step 3: Write `statusctl`**

```bash
cat > desktop/modules/status/statusctl <<'SCRIPT'
#!/bin/bash
#
# 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.
#
# Read, set and watch desktop modes. The modes are files under
# XDG_RUNTIME_DIR holding 0 or 1; a missing file means off.
#
# This talks to the files, not to the shell, so it works while quickshell is
# down. Setting a mode that way records the state without firing its effects;
# the shell sees the change through its own watch and reasserts them.
#
#   statusctl <mode> get          prints 0 or 1
#   statusctl <mode> set 0|1
#   statusctl <mode> toggle
#   statusctl <mode> watch        waybar JSON on every change

set -u

MODES="dnd presentation"
DIR="${XDG_RUNTIME_DIR:-/tmp}"

usage() {
    printf 'usage: %s <%s> <get|set 0|1|toggle|watch>\n' \
           "${0##*/}" "$(printf '%s' "$MODES" | tr ' ' '|')" >&2
    exit 1
}

[[ $# -ge 2 ]] || usage

mode="$1"
action="$2"

# A typo must fail loudly rather than read as a mode that happens to be off.
case " $MODES " in
    *" $mode "*) ;;
    *) printf '%s: unknown mode: %s\n' "${0##*/}" "$mode" >&2; exit 1 ;;
esac

file="$DIR/status.$mode"

read_mode() {
    local v
    # An unreadable file reads as off, deliberately: a missing mode file is
    # the normal state before anything has written one, and the redirect
    # makes that fallback explicit rather than a side effect of a pipeline
    # swallowing cat's exit status.
    v="$(tr -d '[:space:]' < "$file" 2>/dev/null)"
    [[ "$v" == "1" ]] && printf '1' || printf '0'
}

# Write through a temporary file and rename, so no reader ever sees a
# half-written value. This is also what FileView does on the QML side, and it
# is why a watcher has to listen for moved_to as well as close_write.
write_mode() {
    local want="$1" tmp
    tmp="$(mktemp "$DIR/.status.$mode.XXXXXX")" || exit 1
    printf '%s\n' "$want" > "$tmp"
    # The temp file is made in the same directory as the target, so this is a
    # rename rather than a copy, and therefore atomic. A failure here has to
    # be loud: reporting success on a write that did not land would leave the
    # caller and the shell disagreeing about the mode, with an orphan temp
    # file as the only trace.
    mv -f "$tmp" "$file" || { rm -f "$tmp"; exit 1; }
}

emit() {
    local state="$1"
    printf '{"text": "", "alt": "%s", "class": "%s", "tooltip": "%s"}\n' \
           "$state" "$state" "$(tooltip "$state")"
}

tooltip() {
    case "$1" in
        activated)   printf '%s: on' "$mode" ;;
        deactivated) printf '%s: off' "$mode" ;;
        down)        printf '%s: no state file' "$mode" ;;
    esac
}

state_now() {
    [[ -e "$file" ]] || { printf 'down'; return; }
    [[ "$(read_mode)" == "1" ]] && printf 'activated' || printf 'deactivated'
}

case "$action" in
    get)
        read_mode
        printf '\n'
        ;;
    set)
        [[ $# -eq 3 ]] || usage
        case "$3" in
            0|1) write_mode "$3" ;;
            *) usage ;;
        esac
        ;;
    toggle)
        [[ "$(read_mode)" == "1" ]] && write_mode 0 || write_mode 1
        ;;
    watch)
        emit "$(state_now)"
        # Watch the directory rather than the file: an atomic write replaces
        # the file, so a watch held on the old inode dies with it. This is the
        # same trap the mail watcher hit with Xapian.
        inotifywait -q -m -e close_write,moved_to,delete --format '%f' "$DIR" 2>/dev/null |
        while read -r changed; do
            [[ "$changed" == "status.$mode" ]] || continue
            emit "$(state_now)"
        done
        ;;
    *)
        usage
        ;;
esac
SCRIPT
chmod +x desktop/modules/status/statusctl
```

- [ ] **Step 4: Run the test to verify it passes**

```bash
bash desktop/modules/status/test-statusctl.sh
```

Expected: `9 passed, 0 failed`, exit 0.

- [ ] **Step 5: Commit**

```bash
git add desktop/modules/status/statusctl desktop/modules/status/test-statusctl.sh
git commit -m "feat(desktop): add the statusctl CLI and its check

statusctl reads and writes the mode files directly rather than going
through the shell, so it works while quickshell is down. Setting a mode
that way records the state without firing its effects; the shell sees the
change through its own watch and reasserts them.

The watch listens on the directory, not the file: an atomic write replaces
the file, so a watch held on the old inode dies with it. Same trap the mail
watcher hit with Xapian, and the reason moved_to is in the event list.

An unknown mode exits non-zero rather than reading as off, so a typo
cannot masquerade as a mode that happens to be disabled."
```

---

### Task 3: Give the keepalive window an id

**Files:**
- Modify: `desktop/shell.qml:26-34`

**Interfaces:**
- Produces: `keepalive`, referenced by `IdleInhibitor.window` in Task 4. Nothing else changes.

- [ ] **Step 1: Add the id**

In `desktop/shell.qml`, the keepalive `PanelWindow` currently opens with `visible: true`. Add an `id` as its first line and extend the comment:

```qml
    // Quickshell exits once no window is visible, and the drawer is closed
    // most of the time. See AGENTS.md.
    //
    // It is also the window the idle inhibitor attaches to: IdleInhibitor
    // needs a non-null window, and this is the one window that exists for
    // the whole life of the shell.
    PanelWindow {
        id: keepalive
        visible: true
        implicitWidth: 1
        implicitHeight: 1
        color: "transparent"
        exclusionMode: ExclusionMode.Ignore
        mask: Region {}
        WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
    }
```

- [ ] **Step 2: Smoke check**

```bash
timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean"
```

Expected: `clean`.

- [ ] **Step 3: Commit**

```bash
git add desktop/shell.qml
git commit -m "refactor(desktop): name the keepalive window

IdleInhibitor needs a non-null window and this is the only one that lives
for the whole session, so presentation mode attaches to it. Naming it is a
prerequisite for that and changes nothing else."
```

---

### Task 4: Presentation mode and its effects

**Files:**
- Modify: `shared/Status.qml`
- Modify: `desktop/shell.qml` (pass the keepalive window to the singleton)

**Interfaces:**
- Consumes: `keepalive` from Task 3, `breaktimer.sh`.
- Produces: `Status.presentation`, `Status.inhibitWindow` (write-once from `shell.qml`), and the DND restore rule. Tasks 5 and 6 render these.

- [ ] **Step 1: Add the presentation mode, the effects, and the restore rule**

Replace the body of `shared/Status.qml` after the header with this. The `ModeFile` component is unchanged from Task 1; the additions are the second `ModeFile`, `inhibitWindow`, the `IdleInhibitor`, the breaktimer `Process`, and the `setMode` logic.

```qml
pragma Singleton

import Quickshell
import Quickshell.Io
import Quickshell.Wayland
import QtQuick

// Desktop modes as state. One file per mode under $XDG_RUNTIME_DIR, holding
// "0" or "1"; a missing file means off. The runtime directory is tmpfs, so a
// reboot resets every mode with no cleanup code here.
//
// The files are the interface, not this singleton: statusctl reads and writes
// them directly so it works while the shell is down, and the FileView watch
// means an external write repaints the drawer with no polling. It also means
// a mode set from outside still fires its effects, because the watch reaches
// the same handler a tile click would.
Singleton {
    id: root

    readonly property string dir: Quickshell.env("XDG_RUNTIME_DIR") || "/tmp"

    readonly property bool dnd: dndFile.value
    readonly property bool presentation: presFile.value

    readonly property int activeCount: (root.dnd ? 1 : 0) + (root.presentation ? 1 : 0)

    // Set once by shell.qml. IdleInhibitor does nothing with a null window,
    // and the singleton has no window of its own to offer.
    property var inhibitWindow: null

    // What dnd was before presentation mode turned it on, so turning
    // presentation mode off restores it rather than clearing it. Held here
    // rather than in a file: it is meaningful only while presentation mode is
    // on, and presentation mode does not survive a reboot.
    property bool dndBeforePresentation: false

    function setMode(name, on) {
        if (name === "dnd") {
            dndFile.write(on);
        } else if (name === "presentation") {
            presFile.write(on);
        }
    }

    function toggleMode(name) {
        if (name === "dnd") root.setMode("dnd", !root.dnd);
        else if (name === "presentation") root.setMode("presentation", !root.presentation);
    }

    // Effects follow the mode rather than the setter, so a mode set by
    // statusctl while the drawer is closed asserts them too.
    onPresentationChanged: {
        if (root.presentation) {
            root.dndBeforePresentation = root.dnd;
            root.setMode("dnd", true);
            root.runBreaktimer("pause");
        } else {
            root.setMode("dnd", root.dndBeforePresentation);
            root.runBreaktimer("resume");
        }
    }

    function runBreaktimer(verb) {
        breakProc.command = ["breaktimer.sh", verb];
        breakProc.running = false;
        breakProc.running = true;
    }

    // breaktimer owns its own state file; this only calls its verbs. Two
    // writers on that file would race with its daemon loop, which rewrites it
    // on every phase change.
    Process { id: breakProc }

    // Wayland idle inhibit. The compositor advertises
    // zwp_idle_inhibit_manager_v1 and hypridle honours it, so no D-Bus path
    // is needed even though elogind runs here.
    IdleInhibitor {
        window: root.inhibitWindow
        enabled: root.presentation && root.inhibitWindow !== null
    }

    component ModeFile: FileView {
        id: mf

        property bool value: false

        // FileView is documented to fire fileChanged on its own setText, so a
        // write would re-enter this handler. Comparing before assigning makes
        // that harmless: the reparse yields the value just written and the
        // binding does not change.
        function reparse() {
            const t = mf.text().trim();
            const v = (t === "1");
            if (v !== mf.value) mf.value = v;
        }

        function write(on) {
            const s = on ? "1\n" : "0\n";
            mf.value = on;
            mf.setText(s);
        }

        // Both are the documented defaults in 0.3.1, set explicitly because
        // the CLI depends on them: statusctl watches close_write,moved_to
        // precisely because an atomic write lands as a rename, so a future
        // release flipping this default would break the watcher silently.
        atomicWrites: true
        watchChanges: true
        printErrors: false
        onFileChanged: mf.reload()
        onLoaded: mf.reparse()
        // A missing file is the off state, not an error worth logging.
        onLoadFailed: mf.value = false
    }

    ModeFile { id: dndFile; path: root.dir + "/status.dnd" }
    ModeFile { id: presFile; path: root.dir + "/status.presentation" }
}
```

- [ ] **Step 2: Hand the keepalive window to the singleton**

In `desktop/shell.qml`, inside the `PanelWindow` from Task 3, add a completion handler as its last line before the closing brace:

```qml
        WlrLayershell.keyboardFocus: WlrKeyboardFocus.None

        // The singleton has no window of its own and IdleInhibitor needs one.
        Component.onCompleted: Status.inhibitWindow = keepalive
    }
```

- [ ] **Step 3: Smoke check**

```bash
timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean"
```

Expected: `clean`.

- [ ] **Step 4: Confirm the effects fire, with the live shell**

This needs the user's running shell, not the transient smoke instance. Ask the user to restart their drawer (`pkill -x qs` then the three `qs` lines from `autostart.lua`, or a logout), then run:

```bash
statusctl_path=desktop/modules/status/statusctl
bash "$statusctl_path" presentation set 1
sleep 1
echo "dnd now: $(bash "$statusctl_path" dnd get)   (expect 1)"
~/bin/breaktimer.sh status
hyprctl clients | grep -ci inhibit
bash "$statusctl_path" presentation set 0
sleep 1
echo "dnd now: $(bash "$statusctl_path" dnd get)   (expect 0)"
~/bin/breaktimer.sh status
```

Expected: `dnd now: 1`, breaktimer reports `paused`, the inhibitor count rises by one, then `dnd now: 0` and breaktimer reports `running`. Record the actual inhibitor counts in the task report; if the count does not change, the `IdleInhibitor` assumption is wrong and Task 8 gets a trap saying so.

- [ ] **Step 5: Commit**

```bash
git add shared/Status.qml desktop/shell.qml
git commit -m "feat(desktop): add presentation mode and its effects

Presentation mode sets DND, asserts a Wayland idle inhibitor and pauses
breaktimer. The effects hang off the mode property rather than the setter,
so a mode set with statusctl while the drawer is closed asserts them too.

DND has two writers once presentation mode exists, so turning presentation
off restores the value DND had before rather than clearing it, or an
afternoon of hand-set DND would vanish when a talk ends. That prior value
lives in the singleton, not in a file: it means nothing once presentation
mode is off, and presentation mode does not survive a reboot.

breaktimer owns its own state file and is driven only through its verbs.
Two writers on that file would race with its daemon loop."
```

---

### Task 5: The module, tile and row

**Files:**
- Create: `desktop/modules/status/StatusModule.qml`
- Create: `desktop/modules/status/StatusTile.qml`
- Create: `desktop/modules/status/StatusRow.qml`

**Interfaces:**
- Consumes: `Status`, the `Module`, `Tile`, `Switch`, `Theme` root types.
- Produces: `StatusModule` with `name: "status"`, injected into its children as `st`. Task 6 adds the page and registers the module.

- [ ] **Step 1: Create `StatusModule.qml`**

```qml
// 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 "../.."

// Always active: the singleton holds the modes and their effects, and those
// have to be asserted whether or not anyone has opened the drawer. The module
// itself is thin, a tile and a page over Status.
Module {
    id: mod

    name: "status"
    label: "Status"
    alwaysActive: true

    // A toggle glyph, present in Inconsolata Nerd Font.
    icon: "\uf205"

    // The tile renders in its accent while any mode is on.
    active: Status.activeCount > 0

    tileContent: Component { StatusTile { st: mod } }

    page: Component {
        Page {
            title: "Status"
            StatusPage { width: parent.width }
        }
    }
}
```

- [ ] **Step 2: Create `StatusTile.qml`**

```qml
// 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 "../.."

// Injected as st, never mod: a property named the same as the enclosing
// object's id binds to itself and arrives undefined. See AGENTS.md.
Text {
    required property var st

    width: parent ? parent.width : implicitWidth
    elide: Text.ElideRight
    font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 4 }
    color: Status.activeCount > 0 ? Theme.text : Theme.subtext
    text: Status.presentation ? "Presenting"
        : Status.dnd ? "Do not disturb"
        : "All clear"
}
```

- [ ] **Step 3: Create `StatusRow.qml`**

```qml
// 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 "../.."

// One mode: a label, a line saying what it does, and a switch.
Item {
    id: row

    required property string mode
    required property string label
    required property string description
    required property bool value

    implicitHeight: Math.max(texts.implicitHeight, sw.implicitHeight) + 16

    Column {
        id: texts
        anchors {
            left: parent.left
            right: sw.left; rightMargin: 12
            verticalCenter: parent.verticalCenter
        }
        spacing: 2

        Text {
            text: row.label
            font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 2; bold: true }
            color: Theme.text
        }

        Text {
            width: parent.width
            wrapMode: Text.WordWrap
            text: row.description
            font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 4 }
            color: Theme.subtext
        }
    }

    Switch {
        id: sw
        anchors { right: parent.right; verticalCenter: parent.verticalCenter }
        checked: row.value
        onToggled: Status.toggleMode(row.mode)
    }
}
```

- [ ] **Step 4: Smoke check**

```bash
timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean"
```

Expected: `clean`. `StatusPage` does not exist yet, but the page `Component` is lazily loaded, so nothing instantiates it.

- [ ] **Step 5: Commit**

```bash
git add desktop/modules/status/StatusModule.qml desktop/modules/status/StatusTile.qml desktop/modules/status/StatusRow.qml
git commit -m "feat(desktop): add the status module, tile and row

The module is thin because the singleton owns the modes: it is a tile and
a page over Status, always active so the effects hold whether or not the
drawer has been opened.

Injected as st rather than mod, since a component property named the same
as the enclosing object's id binds to itself and arrives undefined."
```

---

### Task 6: The page, and register the module

**Files:**
- Create: `desktop/modules/status/StatusPage.qml`
- Modify: `desktop/shell.qml` (import and module registry)

**Interfaces:**
- Consumes: `StatusRow`, `Status`.
- Produces: the finished module in the drawer grid.

- [ ] **Step 1: Create `StatusPage.qml`**

```qml
// 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 "../.."

// One row per mode. Adding a mode is one file in the singleton and one row
// here, which is the point of a registry rather than two toggles.
Column {
    id: page

    spacing: 4

    StatusRow {
        width: page.width
        mode: "dnd"
        label: "Do not disturb"
        description: "Silences notification popups. Critical ones still appear."
        value: Status.dnd
    }

    Rectangle {
        width: page.width
        height: 1
        color: Qt.alpha(Theme.text, 0.08)
    }

    StatusRow {
        width: page.width
        mode: "presentation"
        label: "Presentation"
        description: "Do not disturb, no screen lock, breaktimer paused."
        value: Status.presentation
    }
}
```

- [ ] **Step 2: Register the module in `desktop/shell.qml`**

Add the import beside the others, keeping them alphabetical:

```qml
import "modules/sound"
import "modules/status"
import "modules/vm"
```

Add the module to the registry. Status goes last before `VmModule`, so the grid reads Sound, Network, Bluetooth, KdeConnect, Mail, Appearance, Status, Machines:

```qml
        modules: [
            SoundModule {},
            NetworkModule {},
            BluetoothModule {},
            KdeConnectModule {},
            MailModule {},
            AppearanceModule {},
            StatusModule {},
            VmModule {},
        ]
```

- [ ] **Step 3: Smoke check**

```bash
timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean"
```

Expected: `clean`.

- [ ] **Step 4: Confirm the page renders and the switches drive the modes**

Hot reload does not pick up a new component file until something that imports the directory reloads, and `shell.qml` was just edited, so the rescan has happened. Ask the user to open the drawer, open the Status page, and confirm: two rows with switches, the tile reads "All clear" when both are off, toggling Do not disturb makes the tile read "Do not disturb", toggling Presentation makes it read "Presenting" and flips the DND switch on as well.

Then confirm the file side agrees:

```bash
cat /run/user/1000/status.dnd /run/user/1000/status.presentation
```

Expected: the values match what the switches show.

- [ ] **Step 5: Commit**

```bash
git add desktop/modules/status/StatusPage.qml desktop/shell.qml
git commit -m "feat(desktop): add the status page and register the module

One row per mode. Adding a mode is one file in the singleton and one row
here, which is what a registry buys over two separate toggles."
```

---

### Task 7: Install the CLI and swap the waybar module

**Files:**
- Modify outside the repo: `~/bin/statusctl` (user installs), the live waybar configuration (user applies)

**Interfaces:**
- Consumes: `statusctl` from Task 2.
- Produces: nothing executable in the repo.

- [ ] **Step 1: Ask the user to install the CLI**

The repo copy is the source; `~/bin` is not in this repository. Ask the user to run:

```bash
install -m 755 desktop/modules/status/statusctl ~/bin/statusctl
statusctl dnd get
```

Expected: `0` or `1`, not a "command not found".

- [ ] **Step 2: Ask the user to replace the waybar idle_inhibitor module**

waybar's built-in `idle_inhibitor` owns its own inhibitor object and cannot indicate a mode owned elsewhere. Left running alongside the registry it asserts a second, independent inhibitor, and idle then resumes only when both release.

Ask the user to create `~/.config/waybar/modules/custom/presentation.jsonc`:

```jsonc
{
    "custom/presentation": {
        "exec": "~/bin/statusctl presentation watch",
        "return-type": "json",
        "on-click": "~/bin/statusctl presentation toggle",
        "format": "{icon}",
        "format-icons": {
            "activated": "󰅶 ",
            "deactivated": "󰾪 ",
            "down": "󰾪 "
        },
        "tooltip": true
    }
}
```

The two glyphs are the ones the built-in module already uses, copied from `~/.config/waybar/modules/idle_inhibitor.jsonc` so the bar does not change appearance. They carry trailing variation selectors; copy the bytes rather than retyping them.

Then in `~/.config/waybar/config.jsonc`: replace the `idle_inhibitor.jsonc` include with the new file, and replace `"idle_inhibitor"` in the module list with `"custom/presentation"`. Reload waybar.

Record in the task report which lines changed, so the change is traceable.

- [ ] **Step 3: Confirm the bar and the drawer agree**

Ask the user to click the waybar glyph and confirm the drawer's Status page switch follows, then toggle the drawer switch and confirm the bar glyph follows. This is the whole point of the file being the interface, and it is the one check that exercises both directions.

- [ ] **Step 4: Confirm only one inhibitor is asserted**

```bash
hyprctl clients | grep -ci inhibit
```

Ask the user to run this with presentation mode off, then on. Expected: the count rises by exactly one, not two. Two would mean the built-in waybar module is still running.

---

### Task 8: README, traps, final check

**Files:**
- Create: `desktop/modules/status/README.md`
- Modify: `AGENTS.md`

**Interfaces:**
- Consumes: the finished module.
- Produces: nothing executable.

- [ ] **Step 1: Write `desktop/modules/status/README.md`**

```markdown
# status

Desktop modes as state: `dnd` and `presentation`, owned by the `Status`
singleton and stored as files under `$XDG_RUNTIME_DIR`.

## The files are the interface

    $XDG_RUNTIME_DIR/status.dnd
    $XDG_RUNTIME_DIR/status.presentation

Each holds `0` or `1`; a missing file means off. That directory is tmpfs, so a
reboot resets every mode and there is no cleanup code. A shell restart does
not: the files outlive the process and the singleton reads them back.

Anything can read a mode with `cat`. `statusctl` is the convenience, not the
mechanism, which is why it keeps working while quickshell is down.

## statusctl

    statusctl <mode> get          prints 0 or 1
    statusctl <mode> set 0|1
    statusctl <mode> toggle
    statusctl <mode> watch        waybar JSON on every change

The repo copy is the source; the user installs it to `~/bin`. `watch` watches
the directory rather than the file, because an atomic write replaces the file
and a watch on the old inode dies with it.

Setting a mode with `statusctl` records the state without firing its effects.
The shell sees the change through its own `FileView` watch and asserts them,
so the effects follow either way. If the shell is down, the state is recorded
and reasserted when it returns.

## Effects

`dnd` has none of its own. It is state the notification daemon reads.

`presentation` sets `dnd`, asserts a Wayland idle inhibitor, and pauses
breaktimer. Turning it off restores `dnd` to the value it had before rather
than clearing it, so hand-set DND survives a presentation.

breaktimer owns `$XDG_RUNTIME_DIR/breaktimer.state`. This module calls
`breaktimer.sh pause|resume` and never writes that file: its daemon loop
rewrites it on every phase change, and two writers would race.

## Waybar

`custom/presentation` reads `statusctl presentation watch`. It replaces
waybar's built-in `idle_inhibitor`, which cannot be kept alongside it: that
module owns its own inhibitor object, so both would have to be released
before the screen could lock.

## The check

    ./test-statusctl.sh

Points `XDG_RUNTIME_DIR` at a temporary directory, so it never touches live
modes. Covers the file format, the atomic write, the toggle, the unknown-mode
error and both watch states.
```

- [ ] **Step 2: Add the traps to `AGENTS.md`**

Append to the per-component notes list, plus whichever of the two unverified claims actually bit during Task 4:

```markdown
- **A `FileView` that writes the file it watches sees its own write.**
  `watchChanges` fires `fileChanged` on `setText()` as well as on an external
  change, so a handler that writes in response to a change loops. The status
  registry compares the reparsed value against the current one and assigns
  only on a difference, which makes the self-write a no-op.
- **`IdleInhibitor` needs a non-null `window`.** It has no window of its own
  and does nothing without one. A singleton therefore cannot assert an
  inhibitor unaided: `shell.qml` hands it the keepalive `PanelWindow`, which
  is the one window that exists for the whole session.
```

- [ ] **Step 3: Run every check**

```bash
bash desktop/modules/status/test-statusctl.sh
bash desktop/modules/mail/test-mail-notify.sh
bash desktop/modules/kdeconnect/test-kdeconnect-state.sh
timeout 8 qs -p ./desktop 2>&1 | grep -E 'ERROR|TypeError|ReferenceError|is not defined|Cannot assign|Unable to assign' && echo "ERRORS ABOVE" || echo "clean"
```

Expected: statusctl `9 passed, 0 failed`; mail 16 of 16; kdeconnect 5 of 5; `clean`.

- [ ] **Step 4: Confirm the process count**

```bash
pgrep -cx qs
```

Expected: the shells the user has running, normally three. Run this after the smoke check has returned, never against a detached process from an earlier call.

- [ ] **Step 5: Ask the user for the final visual pass**

Ask the user to confirm: the Status tile sits between Appearance and Machines; it reads "All clear", "Do not disturb" or "Presenting" as the modes change; the page has two rows with working switches; turning Presentation on flips DND on and turning it off restores DND to what it was; the waybar glyph and the drawer switch follow each other.

- [ ] **Step 6: Commit**

```bash
git add desktop/modules/status/README.md AGENTS.md
git commit -m "docs(status): document the module and record its traps

A FileView fires its own fileChanged on setText, so a handler that writes
in response to a change loops unless it compares first. IdleInhibitor has
no window of its own and does nothing without one, so the singleton is
handed the keepalive window by shell.qml.

Both were read from the documentation while designing and confirmed while
implementing."
```

---

## Notes for the implementer

**Do not write `breaktimer.state`.** The breaktimer daemon rewrites it on every phase change. Call `breaktimer.sh pause|resume` and let it own its file.

**The effects hang off the mode property, not the setter.** This is deliberate: `statusctl presentation set 1` writes a file the shell is watching, and the effects must fire from that path as well as from a tile click. If you move the effects into `setMode`, a mode set from the CLI records state and does nothing.

**The glyph in `StatusModule.qml` is `\uf205`.** It is present in Inconsolata Nerd Font, confirmed against the cmap, so the only open question is whether it reads as a toggle at tile size. Confirm that visually with the user; if it does not, pick another and check the cmap at the path in Verified Facts.

**`statusctl watch` emits an immediate line before entering the loop.** waybar needs a value at startup, not only on the first change.