From 38a32a0c603973b4c0a89fbc13ca6435bd66c623 Mon Sep 17 00:00:00 2001
From: Austin Schaefer <schaefer.austin.p@inbox.eu>
Date: Sun, 20 Sep 2026 09:51:10 +0200
Subject: [PATCH] Apply review feedback: docs, doc comment, lifetimes

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/SPEC.md                     | 20 +++++++++++++-------
 src/notifier.rs                  |  8 +++++---
 systemd/pkgwatch-failure.service |  2 ++
 3 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/docs/SPEC.md b/docs/SPEC.md
index 99acc50..6c08df9 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -409,13 +409,18 @@ Open questions on the schema:
   earlier run. No reject/dismiss command yet — see Status below.)*
 - **Scheduling**: systemd `.service` (oneshot) + `.timer` running it
   periodically, matching the pattern already used for other periodic tasks
-  on this box. *(Implemented — user-level units under `systemd/`, hourly,
-  non-persistent. Install from the main checkout:
-  `cargo build --release && mkdir -p ~/.config/systemd/user &&
-  cp systemd/* ~/.config/systemd/user/ && systemctl --user daemon-reload &&
-  systemctl --user enable --now pkgwatch.timer`. `pkgwatch.service`
-  sets `WorkingDirectory` to `~/dev/pkgwatch` because `packages.d/`,
-  `state/` and `work/` resolve relative to cwd.)*
+  on this box. *(Implemented — user-level units under `systemd/`, run 10s
+  after login and then hourly, non-persistent. Install from the main
+  checkout:*
+
+  ```sh
+  cargo build --release && mkdir -p ~/.config/systemd/user &&
+    cp systemd/* ~/.config/systemd/user/ && systemctl --user daemon-reload &&
+    systemctl --user enable --now pkgwatch.timer
+  ```
+
+  *`pkgwatch.service` sets `WorkingDirectory` to `~/dev/pkgwatch` because
+  `packages.d/`, `state/` and `work/` resolve relative to cwd.)*
 - **Notifications**: `notifier.rs` sends a desktop notification
   (`notify-send`) when a tier 4-6 release is newly queued for review or a
   tier 1-3 release is published; both are best-effort and never fail a
@@ -486,6 +491,7 @@ Open questions on the schema:
       ever actually fails on it.
 - [ ] Not yet implemented: `pkgwatch review <name> --reject` (a pending
       review can only be approved or left pending, not dismissed),
+      per-package `check_interval` (the timer is a fixed hourly tick),
       non-GitHub sources, `minisign`/tier-1
       method, retention/pruning of old versions in the local repo (see
       Scaling > Local repo retention), staggering/auth for GitHub API
diff --git a/src/notifier.rs b/src/notifier.rs
index 4c6cf8f..a7a3bab 100644
--- a/src/notifier.rs
+++ b/src/notifier.rs
@@ -18,7 +18,7 @@ pub enum Event<'a> {
 
 /// (summary, body) for `event` — pure, so the wording is unit-testable
 /// without a notification daemon.
-fn message(event: Event) -> (String, String) {
+fn message(event: Event<'_>) -> (String, String) {
     match event {
         Event::NeedsReview { name, version } => (
             format!("{name} {version} needs review"),
@@ -31,13 +31,15 @@ fn message(event: Event) -> (String, String) {
     }
 }
 
-pub fn notify(event: Event) {
+/// Best-effort desktop notification via the real `notify-send`; never
+/// fails the caller.
+pub fn notify(event: Event<'_>) {
     notify_with(Path::new("notify-send"), event);
 }
 
 /// `notify_send_bin` is injectable for the same reason as
 /// `publisher::publish_with`'s `repo_add_bin`.
-fn notify_with(notify_send_bin: &Path, event: Event) {
+fn notify_with(notify_send_bin: &Path, event: Event<'_>) {
     let (summary, body) = message(event);
     let result = Command::new(notify_send_bin)
         .args(["--app-name=pkgwatch", "--", &summary, &body])
diff --git a/systemd/pkgwatch-failure.service b/systemd/pkgwatch-failure.service
index f40b413..35e2aaf 100644
--- a/systemd/pkgwatch-failure.service
+++ b/systemd/pkgwatch-failure.service
@@ -6,4 +6,6 @@ Description=Notify that a pkgwatch run failed
 
 [Service]
 Type=oneshot
+# Absolute path: systemd requires one, unlike the in-process notifier,
+# which resolves notify-send from PATH.
 ExecStart=/usr/bin/notify-send --app-name=pkgwatch --urgency=critical "pkgwatch run failed" "See: journalctl --user -u pkgwatch.service"