mirror of
https://github.com/kuhyx/steam-backlog-enforcer.git
synced 2026-11-22 01:32:17 +01:00
A running game process was treated as proof of play. On 2026-08-28 the budget
billed ~2h23m while a gatelock screen locker covered the display and the
machine could not be touched at all -- the game was simply still resident.
A tick now bills only when all three hold, evaluated together rather than
short-circuited so the audit log can answer "was the screen ALSO locked?":
* no gatelock guard owns the screen (_screen_hold, via /proc/locks)
* the focused window belongs to a qualifying process or its ancestry
* some input source has been used within idle_grace_seconds (default 300)
Any probe that cannot answer BILLS the tick and is recorded in `degraded`.
A broken detector must never become an unlimited-gaming exploit.
Three findings from measuring this machine rather than assuming:
* /dev/input/js0 here is an *ASRock LED Controller* -- the kernel exposes
the motherboard RGB device as a joystick. A presence check would have
disabled the idle criterion permanently, so _controller_input watches for
real events instead (skipping joydev's synthetic open burst).
* Aseprite's window carries no _NET_WM_PID at all, so focus attribution
falls back to XRes, which asks the server who owns the window rather than
trusting the client to have announced itself.
* /proc/locks reports gatelock's hold without taking it; gatelock's own
read_claim_if_held detects held-ness by acquiring, which would race a
guard every 3 seconds.
Idle pauses also refund the grace period once per walk-away, on the
engaged->paused edge only, never across a day rollover, and never on the first
tick after a restart -- the only place the counter moves backwards.
Everything is recorded to /var/log/steam-backlog-enforcer/budget.jsonl, on
change plus a heartbeat rather than one line per 3s tick. Records name the
qualifying PIDs: reconstructing this incident from journald alone was only
possible by inferring accrual from the spacing of two warning notifications.
Also: refuse to bounce Steam while a game is running. ensure_steam_debug_port
relaunches Steam when the CDP port is closed, which kills the running game --
that is how restarting the daemon to deploy this change ended a live session.
It now defers exactly as it already did for in-flight game updates.
Talks to X through ctypes over one cached connection: at a 3s tick, forking
xprintidle and xprop would cost ~40 forks a minute.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019CEsG6BzHtYR9cHcdxPZqG
165 lines
5.6 KiB
Python
165 lines
5.6 KiB
Python
"""Deciding whether the user is actually playing, not just leaving a game open.
|
|
|
|
A running game process is not evidence of play. The budget was previously billed
|
|
for two hours during which a screen locker covered the display and the machine
|
|
could not be touched at all — the game was simply still resident.
|
|
|
|
Three signals gate a tick, evaluated together rather than short-circuited, so
|
|
that the log can answer "was the screen *also* locked?" after the fact and the
|
|
backdate can tell an idle-only pause from a compound one. The probes themselves
|
|
live in :mod:`_engagement_probes`.
|
|
|
|
This module owns the per-tick verdict and the one piece of state a pure function
|
|
cannot hold: the previous verdict, which the idle backdate needs to recognise an
|
|
engaged-to-paused edge.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import replace
|
|
import logging
|
|
from typing import TYPE_CHECKING
|
|
|
|
from steam_backlog_enforcer._controller_input import ControllerActivity
|
|
from steam_backlog_enforcer._engagement_probes import (
|
|
assess_focus,
|
|
assess_idle,
|
|
assess_screen,
|
|
)
|
|
from steam_backlog_enforcer._engagement_types import (
|
|
STATE_ENGAGED,
|
|
STATE_NOT_APPLICABLE,
|
|
STATE_PAUSED,
|
|
CauseTally,
|
|
EngagementVerdict,
|
|
)
|
|
from steam_backlog_enforcer._screen_hold import holder_lock_path
|
|
from steam_backlog_enforcer._x_probe import XProbe
|
|
|
|
if TYPE_CHECKING:
|
|
from pathlib import Path
|
|
|
|
from steam_backlog_enforcer._playtime_state import PlaytimeRules, PlaytimeState
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
|
|
class EngagementTracker:
|
|
"""Assesses engagement per tick and owns the state the backdate needs."""
|
|
|
|
def __init__(
|
|
self,
|
|
*,
|
|
uid: int,
|
|
probe: XProbe | None = None,
|
|
controller: ControllerActivity | None = None,
|
|
holder_path: Path | None = None,
|
|
) -> None:
|
|
"""Build a tracker over the desktop session owned by *uid*.
|
|
|
|
Args:
|
|
uid: Owner of the desktop session.
|
|
probe: X probe, injected by tests.
|
|
controller: Controller-activity watcher, injected by tests.
|
|
holder_path: gatelock holder lock, injected by tests.
|
|
"""
|
|
self._probe = probe if probe is not None else XProbe()
|
|
self._controller = (
|
|
controller if controller is not None else ControllerActivity()
|
|
)
|
|
self._holder_path = (
|
|
holder_path if holder_path is not None else holder_lock_path(uid)
|
|
)
|
|
self._previous: EngagementVerdict | None = None
|
|
self._previous_day: str | None = None
|
|
|
|
def close(self) -> None:
|
|
"""Release the X connection and controller devices."""
|
|
self._probe.close()
|
|
self._controller.close()
|
|
|
|
def assess(
|
|
self,
|
|
rules: PlaytimeRules,
|
|
*,
|
|
qualifying: set[int],
|
|
now_monotonic: float,
|
|
) -> EngagementVerdict:
|
|
"""Judge whether this tick counts against the budget.
|
|
|
|
Args:
|
|
rules: Policy for this tick.
|
|
qualifying: PIDs that would otherwise count.
|
|
now_monotonic: Monotonic timestamp, for controller-activity ages.
|
|
|
|
Returns:
|
|
The verdict for this tick.
|
|
"""
|
|
if not qualifying:
|
|
return EngagementVerdict(state=STATE_NOT_APPLICABLE)
|
|
|
|
pids = tuple(sorted(qualifying))
|
|
if not rules.engagement_gate:
|
|
return EngagementVerdict(state=STATE_ENGAGED, qualifying=pids)
|
|
|
|
tally = CauseTally()
|
|
|
|
held, holder_pid = assess_screen(self._holder_path, tally)
|
|
focus_pid = assess_focus(self._probe, rules, qualifying, tally)
|
|
idle, controller_idle = assess_idle(
|
|
self._probe, self._controller, rules, tally, now_monotonic
|
|
)
|
|
|
|
return EngagementVerdict(
|
|
state=STATE_PAUSED if tally.causes else STATE_ENGAGED,
|
|
causes=tuple(tally.causes),
|
|
degraded=tuple(tally.degraded),
|
|
idle_seconds=idle,
|
|
controller_idle_seconds=controller_idle,
|
|
screen_held=held,
|
|
holder_pid=holder_pid,
|
|
focus_pid=focus_pid,
|
|
qualifying=pids,
|
|
)
|
|
|
|
def backdate(
|
|
self,
|
|
state: PlaytimeState,
|
|
verdict: EngagementVerdict,
|
|
*,
|
|
rules: PlaytimeRules,
|
|
) -> PlaytimeState:
|
|
"""Refund the idle grace period once per walk-away.
|
|
|
|
Time billed *before* the idle threshold tripped was not play either, so
|
|
the first paused tick of an idle-only spell gives it back. Deliberately
|
|
conservative: it fires only on the engaged-to-paused edge, only when
|
|
idleness is the sole cause, and never across a day rollover — and after
|
|
a daemon restart there is no previous verdict, so nothing is refunded.
|
|
|
|
Args:
|
|
state: Accounting state after this tick's accumulation.
|
|
verdict: This tick's verdict.
|
|
rules: Policy for this tick.
|
|
|
|
Returns:
|
|
The state, with the grace period deducted when all of that holds.
|
|
"""
|
|
previous, previous_day = self._previous, self._previous_day
|
|
self._previous, self._previous_day = verdict, state.day_key
|
|
|
|
if previous is None or previous.state != STATE_ENGAGED:
|
|
return state
|
|
if previous_day != state.day_key:
|
|
return state
|
|
if not verdict.idle_only():
|
|
return state
|
|
|
|
refunded = max(0.0, state.seconds - rules.idle_grace_seconds)
|
|
logger.info(
|
|
"Idle for %.0fs; refunding the %.0fs grace period.",
|
|
verdict.idle_seconds or 0.0,
|
|
state.seconds - refunded,
|
|
)
|
|
return replace(state, seconds=refunded)
|