steam-backlog-enforcer/DOCS-ctl-socket.md

# Control socket: implementation notes

How the root daemon's `ctl.sock` (contract: `DOCS-web-control-api.md`, "Control
socket") is built. Code: `steam_backlog_enforcer/_ctl_*.py`; client for the web
server: `_ctl_client.py` (results in `_ctl_types.py`, errors in `_ctl_protocol.py`).

## Trust

- Root (uid 0) is admitted besides the desktop user: root can already do all of
  this directly, so refusing it protects nothing and it keeps recovery/tests on
  one interface. Any other uid is closed unanswered (client: `DaemonUnreachableError`).
- A second `enforce` (manual run, `--demo`) never takes the socket from a live
  daemon; `--demo` never serves.
- The daemon re-checks the CLI's locks with the same tables
  (`_command_locks.py`): under a total block only `gaming_unblock` works; under
  the manual-pick lock `store_unblock` and `block_gaming` are `locked`.
- Ops run on connection threads and take the enforce loop's `tick_lock`, so they
  never interleave with a pass; the loop reloads state under that lock.

## Differences from the contract

- Daemon-only error codes: `op_failed` (the privileged action ran and failed, or
  an unexpected exception) and `unsupported` (restart asked of a daemon systemd
  does not supervise: the exit would be a stop). Not in `ApiErrorCode`; the web
  server should map unknown daemon codes to a 502.
- The two-phase reply uses `pending_id` (the contract's `PendingAction.id`) and an
  extra `lapse_after_seconds`; the server maps it.
- `block_gaming` is capped at 1..365 days and refused while a block is active.
- `gaming_reset_arm` while one is armed returns the existing pending action
  (same `pending_id`, same `ready_at`): re-arming can neither shorten nor extend
  the wait. Pending resets live in daemon memory, so a daemon restart drops them
  (fail closed: arm again).
- Test-only: `SBE_CTL_TEST_COUNTDOWN_SECONDS` (1..299) in the unit's environment
  shortens the countdown for VM runs. It cannot lengthen it; unset means 300 s.

## Gaming reset

`_gaming_reset.reset_today`, shared with the CLI: zeroes billed time and per-game
attribution, re-arms warnings, releases the mounts, keeps earned time (`carry`,
`budget_seconds`; the old CLI path dropped both), and writes a `manual_adjustment`
record to `/var/log/steam-backlog-enforcer/budget.jsonl` (billed seconds and
per-game breakdown before). That record is the auditable trail; the per-day
history mirrors current billed time, so it shows the day as quiet.

## What a restart does and does not lose

`restart` sets a flag; the enforce loop finishes its pass, runs one more
accounting tick (billing the time since the last tick), leaves an exit-time
marker (`_ctl_gap.py`), and exits 0; `Restart=always` brings it back after
`RestartSec=5`. The new daemon spends the marker on its first tick, billing the
whole downtime. Everything else already lives on disk after every tick:

| State | Survives? | Why |
|---|---|---|
| Billed seconds, per-game attribution | yes | `playtime_state.json` saved every tick; the final tick bills up to the exit, the first tick of the new daemon bills the gap |
| Cutoff / kill-grace timing | yes | `blocked_at` is persisted; `_sustain_block` measures from it |
| Playtime mounts (the block itself) | yes | kernel mount table; `reconcile` is mountinfo-driven. `RuntimeDirectoryPreserve=yes` keeps the stub file |
| Fired warnings, carry ledger | yes | in `PlaytimeState` |
| Open store window | yes (blip) | deadline in `state.json`; startup re-blocks the store once, the first tick re-opens it |
| Total block | yes | lock file, guard-lib |
| Armed gaming reset | no | memory only: arm again (fails closed) |
| Audit-journal "last verdict", history throttle | no | cosmetic: one extra `verdict_change` line, one extra history write |

Why the gap is billed explicitly: the budget clamps each tick's delta to
`2 x ENFORCE_INTERVAL` = 6 s so a suspend cannot inflate it, which would forgive
the restart gap (`RestartSec` + interpreter start + startup pass, seconds to tens
of seconds) and make a restart repeatable free play. The marker is deleted
before use, expires after 300 s and only a requested restart writes one, so a
crash or a long outage still goes through the normal clamp. Downtime nothing
enforces: an unauthorised game started in the gap is killed on the first tick;
the budget cutoff and its mounts persist throughout.

Rate limit: 1 per 10 minutes, persisted in
`/var/lib/steam-backlog-enforcer/ctl_restart.json` (root, 0600) so restarting
the daemon does not reset it.