Apply review feedback: docs, doc comment, lifetimes

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

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,
+  on this box. *(Implemented — user-level units under `systemd/`, run 10s
-  non-persistent. Install from the main checkout:
+  after login and then hourly, non-persistent. Install from the main
-  `cargo build --release && mkdir -p ~/.config/systemd/user &&
+  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`
+    systemctl --user enable --now pkgwatch.timer
-  sets `WorkingDirectory` to `~/dev/pkgwatch` because `packages.d/`,
+  ```
-  `state/` and `work/` resolve relative to cwd.)*
+
+  *`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

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])

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"