From f546ee450eb0e6d4278fecf28794bd533fa4291d Mon Sep 17 00:00:00 2001
From: James Brechtel <git@jamesbrechtel.com>
Date: Sat, 23 May 2026 22:38:55 -0400
Subject: [PATCH] Add converge-wake.service and systemd-sleep hook for
 wake-from-sleep sync

Creates a oneshot user service (converge-wake.service) that runs
converge --sync after the network is online, and a systemd-sleep hook
(/usr/lib/systemd/system-sleep/converge-wake) that triggers the service
for each logged-in user on resume.

Uses After=network-online.target for proper network timing on
NetworkManager/systemd-networkd setups, with a 5-second ExecStartPre
delay as a safety net for netctl and other environments where
network-online.target may not gate on resume.

Updated PKGBUILD and AGENTS.md accordingly.
---
 AGENTS.md                      |  8 +++++---
 PKGBUILD                       | 12 +++++++++++-
 converge-wake.service          | 19 +++++++++++++++++++
 src/converge-wake.service      | 19 +++++++++++++++++++
 src/system-sleep/converge-wake | 14 ++++++++++++++
 5 files changed, 68 insertions(+), 4 deletions(-)
 create mode 100644 converge-wake.service
 create mode 100644 src/converge-wake.service
 create mode 100755 src/system-sleep/converge-wake

diff --git a/AGENTS.md b/AGENTS.md
index b12302e..16fc95a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,9 +18,11 @@ test/TestHelper.hs   # Shared test utilities (temp repos, sentinel files)
 test/GitCommitSpec.hs   # Commit behaviour tests
 test/GitPullSpec.hs     # Pull/rebase tests
 test/GitSafetySpec.hs   # Operation-in-progress detection tests
-SPEC.md              # Human-readable specifications
-converge.example.yaml   # Example config file
-converge.service     # systemd unit file
+SPEC.md                 # Human-readable specifications
+converge.example.yaml    # Example config file
+converge.service         # systemd user service (daemon mode)
+converge-wake.service    # systemd user service (wake-from-sleep sync)
+src/system-sleep/        # systemd-sleep hook scripts
 ```
 
 ## Architecture
diff --git a/PKGBUILD b/PKGBUILD
index 00f32fc..9520b5a 100644
--- a/PKGBUILD
+++ b/PKGBUILD
@@ -15,11 +15,15 @@ optdepends=('converge-relay: realtime push notifications via SSE relay server')
 backup=('etc/converge/config.example.yaml')
 source=(
     "converge.service"
+    "converge-wake.service"
     "converge.example.yaml"
+    "src/system-sleep/converge-wake"
 )
 md5sums=(
     'SKIP'
     'SKIP'
+    'SKIP'
+    'SKIP'
 )
 
 build() {
@@ -54,9 +58,15 @@ package() {
     install -Dm755 "$srcdir/bin/converge" \
         "$pkgdir/usr/bin/converge"
 
-    # User systemd service
+    # User systemd services
     install -Dm644 converge.service \
         "$pkgdir/usr/lib/systemd/user/converge.service"
+    install -Dm644 converge-wake.service \
+        "$pkgdir/usr/lib/systemd/user/converge-wake.service"
+
+    # Sleep hook (runs converge --sync for all logged-in users after resume)
+    install -Dm755 src/system-sleep/converge-wake \
+        "$pkgdir/usr/lib/systemd/system-sleep/converge-wake"
 
     # Example config
     install -Dm644 converge.example.yaml \
diff --git a/converge-wake.service b/converge-wake.service
new file mode 100644
index 0000000..74385b6
--- /dev/null
+++ b/converge-wake.service
@@ -0,0 +1,19 @@
+[Unit]
+Description=Converge - sync repos after waking from sleep
+Documentation=https://github.com/jbrechtel/converge
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/converge --sync
+# Small delay as a safety net for environments (e.g. netctl) where
+# network-online.target may not gate properly on resume, giving the
+# network stack time to reconnect before converge attempts to pull.
+ExecStartPre=/bin/sleep 5
+
+# Allow notify-send to reach the desktop session
+Environment=DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/%U/bus
+
+[Install]
+WantedBy=default.target
diff --git a/src/converge-wake.service b/src/converge-wake.service
new file mode 100644
index 0000000..74385b6
--- /dev/null
+++ b/src/converge-wake.service
@@ -0,0 +1,19 @@
+[Unit]
+Description=Converge - sync repos after waking from sleep
+Documentation=https://github.com/jbrechtel/converge
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/converge --sync
+# Small delay as a safety net for environments (e.g. netctl) where
+# network-online.target may not gate properly on resume, giving the
+# network stack time to reconnect before converge attempts to pull.
+ExecStartPre=/bin/sleep 5
+
+# Allow notify-send to reach the desktop session
+Environment=DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/%U/bus
+
+[Install]
+WantedBy=default.target
diff --git a/src/system-sleep/converge-wake b/src/system-sleep/converge-wake
new file mode 100755
index 0000000..d92ab68
--- /dev/null
+++ b/src/system-sleep/converge-wake
@@ -0,0 +1,14 @@
+#!/bin/sh
+# Hook for systemd-sleep: run converge --sync for each logged-in user after resume.
+# Installed to /usr/lib/systemd/system-sleep/converge-wake.
+# Called with $1 = "pre" (before sleep) or "post" (after resume).
+
+if [ "$1" = "post" ]; then
+    # The converge-wake.service has After=network-online.target, so systemd
+    # won't run the actual sync until the network stack is restored. This
+    # hook only needs to request the start.
+    loginctl list-users --no-legend 2>/dev/null | while read uid name rest; do
+        [ "$uid" -ge 1000 ] 2>/dev/null || continue
+        su "$name" -c "XDG_RUNTIME_DIR=/run/user/$uid systemctl --user start converge-wake.service" 2>/dev/null || true
+    done
+fi