Enforce PIA split tunnel config via settings.json watchdog

[smartwatermelon]

Problem

PIA frequently "forgets" its split tunnel configuration (unchecks the checkbox in the GUI). When this happens with the Stage 1 inversion architecture, all traffic goes through VPN — including Plex, which becomes unusable through a multi-hop overseas VPN connection.

The Stage 1 inversion makes this safe (no IP leak), but it causes a functional outage for Plex until someone notices and re-checks the box.

Discovery

PIA stores its full config in plain JSON at:

/Library/Preferences/com.privateinternetaccess.vpn/settings.json

Root-owned, world-readable. Key fields:

{
  "splitTunnelEnabled": true,
  "splitTunnelRules": [
    {"mode": "exclude", "path": "/Applications/Plex Media Server.app"},
    {"mode": "exclude", "path": "/Applications/Backblaze.app"},
    {"mode": "exclude", "path": "/Applications/No-IP DUC.app"},
    {"mode": "exclude", "path": "/System/Volumes/Preboot/Cryptexes/App/System/Applications/Safari.app"}
  ],
  "bypassSubnets": [{"mode": "exclude", "subnet": "10.0.15.0/24"}],
  "killswitch": "on"
}

Notably, the file showed splitTunnelEnabled: true even when the GUI checkbox appeared unchecked — PIA's GUI state and config file may desync.

Proposed Solution

A watchdog script (LaunchAgent or addition to vpn-monitor.sh) that:

1. Periodically reads settings.json
2. If splitTunnelEnabled is false or bypass rules are missing, rewrites the correct values
3. Restarts the PIA daemon to pick up the change

Open Questions

• How to restart PIA from CLI? (piactl? kill the daemon? launchctl?)
• Does PIA re-read settings.json on its own, or does it need a restart?
• Does PIA overwrite settings.json on quit (stomping our changes)?
• Should this be a standalone script or integrated into vpn-monitor.sh?
• What's the right polling interval? (less frequent than VPN monitor — maybe 60s)

Files

File	Contents
/Library/Preferences/com.privateinternetaccess.vpn/settings.json	Full PIA config (split tunnel, kill switch, protocol, etc.)
/Library/Preferences/com.privateinternetaccess.vpn/data.json	PIA state data (~190KB)
/Library/Preferences/com.privateinternetaccess.vpn/account.json	Account info (root-only readable)
~/Library/Preferences/com.privateinternetaccess.vpn/clientsettings.json	Per-user client settings

Context

• Part of the VPN protection system (see docs/vpn-transmission.md)
• Stage 1 (PIA inversion) makes forgetting safe but causes Plex outage
• Stage 2 (vpn-monitor) handles VPN drops but not PIA config resets
• This would be a "Stage 1.5" — enforcing the PIA config that Stage 1 depends on

[smartwatermelon]

Implemented in PR #63 (5d9a1b7) and deployed live on tilsit (2026-02-13).

What was built:

• app-setup/templates/pia-split-tunnel-monitor.sh — polls settings.json every 60s, compares against saved reference, auto-restores via piactl -u applysettings + disconnect/connect cycle
• Deployed by transmission-setup.sh (saves reference + deploys template + creates LaunchAgent)
• Backoff after 3 failed fix attempts (5 min cooldown)
• Uses python3 for JSON parsing (no jq on stock macOS)

Answers to the open questions from this issue:

• How to restart PIA: piactl disconnect && sleep 3 && piactl connect
• Does PIA re-read settings.json? No — needs disconnect/connect cycle
• Does PIA overwrite on quit? The monitor reads from the file, doesn't write to it directly; piactl -u applysettings merges into the daemon which writes settings.json
• Standalone or integrated? Standalone (different polling frequency, different urgency, independent restart/rollback)
• Polling interval? 60 seconds

Live verification: Toggled split tunnel off in PIA GUI → monitor detected drift within 60s → restored config → PIA reconnected → VPN monitor independently handled the transient VPN drop during reconnection (killed Transmission, relaunched after VPN restored). Both monitors composed correctly with no coordination needed.