screen-locker/README.md
Krzysztof kuhy Rudnicki 9e7f536f96
Some checks are pending
dependency freshness / dependencies on newest stable (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
pre-commit / pre-commit (${{ matrix.group }}) (flutter, flutter-analyze, ) (push) Waiting to run
pre-commit / pre-commit (${{ matrix.group }}) (mypy, mypy, ) (push) Waiting to run
pre-commit / pre-commit (${{ matrix.group }}) (pylint, pylint, ) (push) Waiting to run
pre-commit / pre-commit (${{ matrix.group }}) (rest, , mypy,pylint,flutter-analyze) (push) Waiting to run
Tests / test (push) Waiting to run
Tests / lock-popup-safety (push) Waiting to run
Tests / flutter test (shard ${{ matrix.shard }}) (0) (push) Waiting to run
Tests / flutter test (shard ${{ matrix.shard }}) (1) (push) Waiting to run
Tests / flutter test (shard ${{ matrix.shard }}) (2) (push) Waiting to run
Tests / flutter test (shard ${{ matrix.shard }}) (3) (push) Waiting to run
Tests / flutter test (shard ${{ matrix.shard }}) (4) (push) Waiting to run
Tests / flutter test (shard ${{ matrix.shard }}) (5) (push) Waiting to run
Tests / flutter test (shard ${{ matrix.shard }}) (6) (push) Waiting to run
Tests / flutter test (shard ${{ matrix.shard }}) (7) (push) Waiting to run
Tests / flutter test (shard ${{ matrix.shard }}) (8) (push) Waiting to run
Tests / flutter test (shard ${{ matrix.shard }}) (9) (push) Waiting to run
Tests / flutter-coverage (push) Blocked by required conditions
Tests / web-coverage (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
Report errors and stalls to the shared board
gatelock error_report: uncaught, thread and Tk callback errors plus a
frozen lock window over 1 s go to the app-errors spool. The pre-commit
pylint env moves to gatelock 0.16.0, the version requirements pin.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 22:00:15 +01:00

5.8 KiB

screen-locker

Tkinter/systemd screen locker with workout tracking, shared sick days, and wake-alarm integration. It enforces a workout cadence by locking the screen until a verified (RunnerUp, StrongLifts) or budgeted manual workout is logged.

Sick days

A sick day is a date in the fleet-wide sickdays pool, nothing else: no budget, countdown, justification or debt. The lock screen's I'm sick button (retry screen, no-phone screen and the Tue-Thu prompt) marks today with one tap and unlocks; sickdays add or the phone do the same. On a sick day the workout lock stands down, wake-alarm's workday penalty is void, and shutdown is 20:00 plus the gaming pay of everything credited that day, capped at 23:00 (earned_time.sick_shutdown_from). A day marked after its daily reset is raised to it by the next live pass (_sick_floor), and every later credit that day raises it again.

A credit landing after tonight's shutdown adds its reward to that shutdown, like any other (18:00 + 2h = 20:00 even for a run ending at 19:58); unpaid evening gates hold the PC until 23:00 instead. install.sh migrates the old sick_history.json dates into the pool once (scripts/migrate_sick_history.py).

A sick day may keep lockers (sickdays add --keep workout). A kept workout lock behaves exactly as on a normal day (lock, quota, relaxed-day penalty on that date); only the 20:00 shutdown floor still applies, since it belongs to the day, not to a locker. The one-tap button keeps nothing. The missed-alarm penalty is void on its ring day only if alarm is off, and on its penalty day only if workout is off. All of it goes through _sick.stands_down_workout.

Shutdown time

Every day starts at 19:00 from 2026-10-01, 20:00 before it (base_minutes() in screen_locker/_shutdown_base.py) and bonuses push it later, capped at 23:00: the first counted workout +2h, each further one +1h, an accepted LeetCode submission that day +1h (flat, read from leetcode-guard's ledger, once per day), and a credited paper-book reading session of 20+ pages / 20+ minutes +1h (flat, read from book-guard's ledger, once per day, keyed on when the reading ended). The config is re-derived from those sources on each new day, so nothing has to be "remembered" across reboots.

A RunnerUp run is credited from its TCX export, found in the WebDAV drop directory RunnerUp uploads to on this machine (~/data/cloud/RunnerUp/, plus processed/ once endurain-import has taken it) or, when a phone is adb-visible, in /sdcard/Documents/RunnerUp/. The 15-minute workout-sync.timer scans both, so a run finished after 20:00 pushes the hour later without the phone being plugged in; the per-minute shutdown check then lifts the night lockdown on its own once the hour is past "now" (digital-wellbeing's check script).

Runs and walks are credited by ONE rule, whatever the TCX sport or the _Walking file-name suffix (RunnerUp's files and the workout app's alike): a day's activities are summed, and the day counts once their distance reaches 3.5 km (5% GPS tolerance) OR their moving time reaches the shared duration bar (30 min minus the hidden leeway). Both are summed over the track cut into windows of at least 10 s, each judged by its average speed: faster than 25 km/h (a vehicle or a GPS jump) counts neither time nor distance; moving time needs 0.5 m/s or more (1 m/s across a signal dropout longer than 30 s, so a pause earns nothing but a run through a dropout keeps its time). Files without trackpoints earn nothing (the lap totals are never used). The reward is the usual one workout credit per day (runnerup_verified:<date>); the log's activity field is display only. Code: screen_locker/_walk_tcx.py.

Retiring RunnerUp. A week after the PC first credits a run recorded by the workout app (TCX author kuhy workout_app), runnerup-retire.timer (daily, retries until the phone is attached) backs /sdcard/Documents/RunnerUp up to ~/data/cloud/RunnerUp/runnerup_phone_backup_<date>/ and uninstalls org.runnerup.free, once the app's .workout_app_import.json matches processed/; no app run, no uninstall. python3 -m screen_locker.runnerup_retire --status / --dry-run change nothing.

Error reports

Every uncaught, thread or Tk callback error, and any freeze of the lock window over 1 s, goes to the shared app-errors spool through gatelock.error_report (screen_locker/_errors.py, installed by the CLI for every mode). The PC's app-errors timer turns each one into a ticket on the todoImplementer board (kuhyx/utils DOCS-app-errors.md). Nothing shows on screen.

MCP server (Claude Code integration)

screen-locker exposes a read-only MCP server (screen_locker._mcp) so Claude Code and its subagents can query workout compliance and the lock-decision state through typed tools — without shelling out to the screen-locker-status CLI or opening the Tk window.

  • Read-only tools: get_status (full status snapshot), get_summary (one-line i3blocks summary + ok/warn/lock state word), explain_lock (why the screen is / isn't locked right now), get_flags (the individual boolean lock-decision predicates for today).
  • There are no write/action tools, by design. Nothing here logs a workout or mutates state — workouts are logged only from RunnerUp-verified TCX data, never from a caller's claim. No tool exposes the sync token or any HMAC key.

The mcp SDK is an optional dependency (pip install -e '.[mcp]'), kept out of the CLI/systemd system-python path. One-time setup of the dedicated venv that Claude Code spawns:

./scripts/setup_mcp.sh

Registration lives in the checked-in .mcp.json (project scope). Restart Claude Code in this repo and approve the project MCP-server prompt for it to load. Verify with claude mcp list.