# screen-lock

The lock screen, idle timeouts and display power as one module (novox/hq ADR 0208, research
026/04).

- Installs `xss-lock` and the distribution's `i3lock`. Claims the mesh's `node-lock-screen` seat and
  serves its verb `lock`. Requires `x11-display` on its own machine.
- **Declares absent** (ADR 0180), as replaced and not coming back:
  - `i3lock-color`, the colour build from the user repository;
  - `xscreensaver`, a second screensaver that was installed and deliberately never started.
- Places the locker `~/.local/bin/screen-lock`. The lock key (`$mod+Delete`) is the `i3` module's.
  It asks logind to lock and names no locker, so it does not depend on which module holds the seat.
- At session start, through the `xinitrc` slot `normal`, it:
  - sets the timeouts: lock after 30 minutes idle, displays to standby and suspend at 30 minutes and
    off at 60;
  - starts `xss-lock --transfer-sleep-lock`, which runs the locker on idle, before suspend and on
    logind's Lock, so the lock key, a closed lid and a suspend all lead to one locker.

  xss-lock stays out of the units on purpose. It must find its own login session, and a user unit
  runs in the service manager's session instead, where xss-lock silently finds none.

## Tools

| tool | does |
|---|---|
| `node-lock-screen.lock` | lock now, through logind, so the session's one locker answers; answers since when |
| `screen_lock_idle` | the idle and display power timeouts in force; change any of them for this session |
| `screen_lock_inhibit` | keep the screen on and unlocked for N minutes, then restore; 0 ends it early |
| `screen_lock_locked` | locked or not and since when, whether xss-lock runs, whether an inhibition holds |

An inhibition runs under the account's service manager (`screen-lock-inhibit.service`). Stopping it
restores the timeouts at once. It holds off the idle lock and display power only: a lock asked for by
hand, by the lid or before suspend still locks.

## Decided: the distribution's i3lock now

The colour build lives in the user repository, and the colours are the only difference. The module
uses the official `i3lock` (black, failed attempts shown, an empty Enter ignored). The colour build
can come back as a pinned archive of this module (ADR 0205). That is a follow-up, and only the
locker's options change with it.

## What it improves on what was found

- **The machine no longer waits for the unlock to suspend.** The found wrapper started i3lock with
  xss-lock's sleep lock inherited, so a suspend was held until logind's delay ran out. The new locker
  follows xss-lock's own pattern: the lock is released as soon as i3lock is up.
- **One locker.** A second lock while locked does nothing. The power menu locks through logind
  instead of starting its own i3lock.
- **The respawn loop ends with the session.** The found loop kept retrying every two seconds after
  logout.
- **The timeouts are set once, in one place.** On the laptop, measured on 2026-10-04, the screensaver
  timeout in force was 600 s, not the 1800 s the start script asked for.

## What it leaves as found

- `~/.xscreensaver`, xscreensaver's configuration file. Remove it once the package is gone.
- `~/scripts/my-i3lock`, the predecessor's wrapper, which only the colour build understands.

## Migration (ADR 0182)

1. **Before the first push,** remove the colour build by hand: `sudo pacman -R i3lock-color`.
   `pacman --noconfirm` will not replace a conflicting package. If the host installs `i3lock` before
   it removes `i3lock-color`, the first push fails on the conflict.
2. Once the `xorg` module writes the session's start, delete from your own part of `~/.xinitrc`:
   - the `xset s` and `xset dpms` lines;
   - the `while true; do xss-lock … my-i3lock; …; done &` loop.
3. Delete `~/.xscreensaver` and `~/scripts/my-i3lock`.

## Blockers

- `node-lock-screen`, `x11-display` and the `xinitrc` slot are ADR 0208's. Until the controller knows
  them, `mctl` reads them as unknown.
- `xset` comes with the display server's module (`xorg`).