# Settings capability and action interface

This is a host-tested userspace checkpoint for the coherent shell, not a
rendered Settings surface or physical acceptance. The launcher consumes the
JSON interface asynchronously so capability reads and power commands cannot
block touch dispatch. No coherent-shell task is completed by this file alone.

## Protocol

`k230-settings status` returns `schema: 1` and a `controls` object containing
`network`, `brightness`, `keyboard` and `motion`. Each control has `state`,
`value` and `label`; optional fields include `action`, `unit` and `detail`.
States distinguish `unavailable`, `read-only`, `writable` and `action`.

- Network carrier describes `link-up` or `disconnected`, never Internet
  reachability. Unknown carrier remains unavailable. Interface identifiers,
  addresses, SSIDs and command output are not returned.
- Brightness requires exactly one real sysfs backlight with a readable actual
  value. The shell user's existing file permissions determine writability;
  the helper adds no privilege. `brightness PERCENT` reports `pending` while
  the confirmed hardware value differs, retaining that confirmed value.
- Keyboard is an action only when the current user's wvkbd process exists.
  `keyboard-toggle` targets that user and exact process name. A successful
  signal means requested, not proof that the keyboard appeared.
- Reduced motion is read-only when the integration supplies the actual
  session value in `K230_SETTINGS_REDUCED_MOTION=0|1`; otherwise unavailable.
  Runtime motion preference updates remain to be integrated with both owners.

`request reboot|poweroff` returns a confirmation label and opaque token, valid
for 30 seconds. The UI must show this separate confirmation and Cancel.
`cancel TOKEN` performs no power action. `confirm TOKEN` consumes the token
before attempting the exact noninteractive sudo/systemctl command. Replacement,
replay and expiration fail. Denial returns `failed` and a retry route, which
must start a new confirmation. Success means requested, not observed restart.

Only the two existing image sudo rules authorize power actions. The default
runtime path is `/run/shell/settings`, a mode-0700 directory owned by the
session user. Pending confirmation is transient and requires no home state.
External commands have a three-second timeout and discard their output.

## Host evidence

On 2026-09-24, `python3 tests/test_device_settings.py` passed nine tests:
actual sysfs capability parsing, absent/read-only/ambiguous controls, pending
brightness, no battery/network identifiers, fresh home, cancellation,
denial/replay, expiration/replacement, runtime ownership, and command timeout.
Sysfs fixtures and injected command results do not prove device behavior.
The tests explicitly reject the planned `scroll` and `flick-stop` cases until
those UI behaviors have their own actual input tests.

`nix build .#handheld-settings --no-link --print-out-paths --max-jobs 1 --cores 8`
also passed, producing
`/nix/store/yabiwy3maplzxbbhbnk97206jcaxl978-k230-settings`. This wraps the helper
with the cross-package Python, procps and systemd paths; it is package proof,
not a running Settings surface.

The explicit operation allowlist correction was rebuilt after review, producing
`/nix/store/46sw7cwipb8g0pfjqa7vry4x1x65345g-k230-settings`. The same nine host
tests pass, including an unexpected operation with an otherwise valid token;
it neither executes an action nor consumes the pending confirmation.

Remaining: launcher integration and asynchronous action feedback,
real Settings scroll/gesture checks, installed image and board observations.