# User units

This directory contains the user services, timers and targets supervised by
`systemd --user`. Unit files are the source of truth for exact commands and
dependencies; this README records their purpose and operational interfaces.

## Package status

`package-status-refresh.timer` becomes due two minutes after boot and then
every 30 minutes. It runs the static oneshot service
`package-status-refresh.service`, which calls `package-status-refresh.sh`.

The refresher:

- uses `checkupdates` with a dedicated temporary package database;
- counts repository updates and local orphan packages;
- avoids reading while Pacman holds its database lock;
- discards results if a package transaction overlaps the check;
- preserves the previous valid cache after network or mirror failures; and
- atomically replaces `~/.cache/package-status/status` on success.

`~/.cache/package-status/last-attempt` supports the shell's five-minute retry
backoff. Exit status 75 means Pacman was active or local package state changed
during the refresh; the service treats that as an expected outcome.

The Bash repository reads the cache without blocking terminal startup. Its
status module may request a non-blocking refresh when the cache is stale. The
profile repository's Arch `update` function does the same after a successful
upgrade.

Enable and inspect the timer with:

```sh
systemctl --user enable --now package-status-refresh.timer
systemctl --user list-timers package-status-refresh.timer
systemctl --user status package-status-refresh.service
journalctl --user -u package-status-refresh.service
```

The refresher requires Pacman, Fakeroot and `checkupdates` from
`pacman-contrib`.

## Mango session

`mango-session.target` groups graphical services that require an initialized
Wayland session. Mango starts the target after importing its display and D-Bus
environment into the user manager.

Target members are:

- `waybar.service`
- `swww.service`
- `blueman-applet.service`
- `polkit-gnome-agent.service`
- `gcr-prompter.service`
- `gnome-keyring-session.service`
- `swayidle.service`
- `mango-tag-osd.service`

Stopping the target stops its `PartOf=` services with the compositor session.

## Audio and speech

- `audio-resume-monitor.service` watches logind for resume events and runs
  `audio-resume-recover.sh` to rebuild PipeWire/Bluetooth audio state.
- `kokoro.service` supervises the persistent local Kokoro text-to-speech
  server and follows the PipeWire lifecycle.

## Mounts and backups

Remote storage units include the Wasabi S3 mounts, encrypted Wasabi data mount
and Ultra.cc rclone mount. `wasabi-data-crypt.target` keeps the encrypted mount
available for interactive use. See `../MOUNTS.md` for mount architecture and
operating details.

`backup-pass.timer` runs at 10:00 and 22:00. Its service requires the encrypted
Wasabi data mount and copies timestamped KeePass database backups using
`backup-pass.sh`.

## SSH proxies

`proxy@.service` starts mutually exclusive SOCKS proxy profiles defined in
`~/.ssh/config`:

```sh
systemctl --user start proxy@alice
systemctl --user start proxy@red
systemctl --user stop proxy@red
```

Add new mutually exclusive instances to the template unit's `Conflicts=` list.

`socks-red.service` is a separate persistent SOCKS proxy on
`127.0.0.1:1188` using `ray@red.isnet.uk`:

```sh
systemctl --user enable --now socks-red.service
```