testsAndMisc/scripts/digital_wellbeing/README_MIDNIGHT_SHUTDOWN_LLM.md

278 lines
10 KiB
Markdown

# Midnight Shutdown System - LLM Reference Guide
> **For AI assistants**: This document explains the automatic shutdown system so you can make correct modifications.
## System Purpose
Automatically shut down the PC during configured time windows to enforce healthy sleep schedules:
- **Monday-Wednesday**: Shutdown at 24:00 (midnight)
- **Thursday-Sunday**: Shutdown at 24:00 (midnight)
- **Morning**: Safe time starts at 00:00 (effectively no morning block)
The times above are defaults; actual values in `/etc/shutdown-schedule.conf`.
## Architecture Overview
```
┌─────────────────────────────────────────────────────────────────────┐
│ SHUTDOWN SYSTEM LAYERS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Layer 1: Systemd Timer │
│ ───────────────────── │
│ day-specific-shutdown.timer fires every minute │
│ day-specific-shutdown.service runs the check script │
│ │
│ Layer 2: Check Script │
│ ──────────────────── │
│ /usr/local/bin/day-specific-shutdown-check.sh │
│ Reads config, checks current time, initiates shutdown if in window │
│ │
│ Layer 3: Config Protection │
│ ──────────────────────── │
│ /etc/shutdown-schedule.conf has chattr +i │
│ Canonical copy at /usr/local/share/locked-shutdown-schedule.conf │
│ Path watcher auto-restores if tampered │
│ │
│ Layer 4: Timer Monitor │
│ ───────────────────── │
│ shutdown-timer-monitor.service watches timer status │
│ Re-enables timer if user tries to disable it │
│ │
│ Layer 5: Script Protection │
│ ──────────────────────── │
│ Setup script blocks making schedule MORE LENIENT │
│ Can only make it STRICTER without the unlock script │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
## File Locations
| File | Purpose | Protection |
|------|---------|------------|
| `/etc/shutdown-schedule.conf` | Runtime config | chattr +i, path watcher |
| `/usr/local/share/locked-shutdown-schedule.conf` | Canonical copy | chattr +i |
| `/usr/local/bin/day-specific-shutdown-check.sh` | Shutdown logic | None |
| `/usr/local/bin/day-specific-shutdown-manager.sh` | Status/management | None |
| `/usr/local/bin/shutdown-timer-monitor.sh` | Timer re-enabler | None |
| `/usr/local/sbin/enforce-shutdown-schedule.sh` | Config restoration | None |
| `/usr/local/sbin/unlock-shutdown-schedule` | Delayed config edit | None |
| `/etc/systemd/system/day-specific-shutdown.timer` | Timer unit | systemd |
| `/etc/systemd/system/day-specific-shutdown.service` | Service unit | systemd |
| `/etc/systemd/system/shutdown-schedule-guard.path` | Config watcher | systemd |
| `/etc/systemd/system/shutdown-schedule-guard.service` | Enforcement | systemd |
| `/etc/systemd/system/shutdown-timer-monitor.service` | Timer guardian | systemd |
| `/var/log/shutdown-schedule-guard.log` | Tampering log | None |
## Config File Format
```bash
# /etc/shutdown-schedule.conf
# Shutdown hour for Monday-Wednesday (24-hour format)
MON_WED_HOUR=21
# Shutdown hour for Thursday-Sunday (24-hour format)
THU_SUN_HOUR=22
# Morning end hour (shutdown window ends at this hour)
MORNING_END_HOUR=5
```
**Interpretation**:
- Mon-Wed: Shutdown if current hour >= 21 OR current hour < 5
- Thu-Sun: Shutdown if current hour >= 22 OR current hour < 5
## Schedule Protection Logic
The setup script (`setup_midnight_shutdown.sh`) has constants at the top:
```bash
SCHEDULE_MON_WED_HOUR=24
SCHEDULE_THU_SUN_HOUR=24
SCHEDULE_MORNING_END_HOUR=0
```
When re-run, it compares these to the canonical config:
| Change Type | Action |
|-------------|--------|
| Making shutdown EARLIER | ✅ Allowed without unlock |
| Making shutdown LATER | ❌ Blocked, requires unlock |
| Making morning end EARLIER | ❌ Always blocked |
| Making morning end LATER | ✅ Allowed (extends shutdown window) |
Example blocked attempt:
```
╔══════════════════════════════════════════════════════════════════╗
║ ❌ SCHEDULE MODIFICATION BLOCKED - CHEATING DETECTED! ❌ ║
╚══════════════════════════════════════════════════════════════════╝
You modified the script to make the shutdown schedule MORE LENIENT:
• Mon-Wed shutdown: 21:00 → 23:00 (later)
Nice try! But this is exactly the kind of late-night bargaining
that this protection is designed to prevent. 😉
```
## Unlock Script Behavior
`/usr/local/sbin/unlock-shutdown-schedule`:
1. Stops `shutdown-schedule-guard.path`
2. Removes chattr from both config files
3. Opens editor on temp copy
4. Checks what changed:
- **Stricter (earlier)**: No delay, applies immediately
- **Lenient (later)**: 45-second countdown, then applies
- **Lower morning end**: **ALWAYS BLOCKED** (cannot shorten window)
5. Updates both config and canonical
6. Re-applies chattr +i
7. Restarts path watcher
## Integration Points
### i3blocks Countdown
`i3blocks/shutdown_countdown.sh` reads the config to show time remaining:
```bash
source /etc/shutdown-schedule.conf
# Calculates and displays "Shutdown in X:XX"
```
### Screen Locker
`screen_lock.py` can adjust shutdown time:
- **Sick day**: Moves shutdown 1.5 hours EARLIER (penalty)
- **Workout completed**: Moves shutdown 1.5 hours LATER (reward)
Uses `adjust_shutdown_schedule.sh` helper script.
## Systemd Units
### Timer (fires every minute)
```ini
[Timer]
OnCalendar=*:*:00
Persistent=false
AccuracySec=1s
```
### Check Service
```ini
[Service]
Type=oneshot
ExecStart=/usr/local/bin/day-specific-shutdown-check.sh
```
### Path Watcher
```ini
[Path]
PathChanged=/etc/shutdown-schedule.conf
Unit=shutdown-schedule-guard.service
```
## Check Script Logic
```bash
# Pseudocode for day-specific-shutdown-check.sh
source /etc/shutdown-schedule.conf
day=$(date +%u) # 1=Monday, 7=Sunday
hour=$(date +%H)
if [[ $day -le 3 ]]; then
shutdown_hour=$MON_WED_HOUR
else
shutdown_hour=$THU_SUN_HOUR
fi
# Check if in shutdown window
if [[ $hour -ge $shutdown_hour ]] || [[ $hour -lt $MORNING_END_HOUR ]]; then
systemctl poweroff
fi
```
## Common Tasks
### Check Current Status
```bash
/usr/local/bin/day-specific-shutdown-manager.sh status
# Or run setup script with 'status' argument
```
### Make Schedule Stricter
Edit the constants in `setup_midnight_shutdown.sh`:
```bash
SCHEDULE_MON_WED_HOUR=20 # Changed from 21 to 20 (earlier)
```
Then re-run:
```bash
sudo ./setup_midnight_shutdown.sh
```
### Make Schedule More Lenient (Requires Unlock)
```bash
sudo /usr/local/sbin/unlock-shutdown-schedule
# Wait for delay, edit config, save
```
### Disable Timer (Will Be Re-Enabled!)
```bash
sudo systemctl disable --now day-specific-shutdown.timer
# Monitor service will re-enable it automatically
```
### Check Protection Status
```bash
lsattr /etc/shutdown-schedule.conf
# Should show: ----i--------e--
systemctl status shutdown-schedule-guard.path
systemctl status shutdown-timer-monitor.service
```
## KNOWN VULNERABILITIES
1. **Information Disclosure**: Error messages tell user exactly how to bypass
2. **Unlock Script Discoverable**: Path mentioned in error messages
3. **Timer Monitor Killable**: User can stop the monitor then the timer
4. **Check Script Unprotected**: `/usr/local/bin/day-specific-shutdown-check.sh` can be edited
**TODO**:
- Remove helpful bypass instructions from error messages
- Rename unlock script to obscure name
- Protect check script with integrity verification
## Troubleshooting
### Timer not firing
```bash
systemctl status day-specific-shutdown.timer
systemctl list-timers | grep shutdown
```
### Config not being enforced
```bash
# Check path watcher
systemctl status shutdown-schedule-guard.path
# Manually trigger enforcement
sudo /usr/local/sbin/enforce-shutdown-schedule.sh
```
### Wrong time shown in i3blocks
```bash
# Verify config
cat /etc/shutdown-schedule.conf
# Check i3blocks config
cat ~/.config/i3blocks/config | grep shutdown
```
## DO NOT
1. ❌ Edit setup script constants to make schedule later (will be blocked)
2. ❌ Delete canonical config (breaks restoration)
3. ❌ Stop `shutdown-timer-monitor.service` (timer will be re-enabled anyway)
4. ❌ Modify check script to skip shutdown (defeats purpose)
5. ❌ Lower `MORNING_END_HOUR` (always blocked, shortens shutdown window)