fix(calendar-sync): run the sync from a timer instead of the agenda hook

The hourly timer armed itself from org-agenda-mode-hook, so a session where
I never opened the agenda never synced at all. After a reboot that is every
session until the first agenda call. I found it with all three calendar
files still frozen at the pre-reboot write, five hours stale.

The deferral had a real reason. Feed URLs behind :secret-host live in
authinfo.gpg, and starting at load would prompt for a passphrase on a cold
gpg-agent. The cost was worse than what it bought.

A user timer owns the schedule now, every ten minutes.
calendar-sync-auto-start defaults to nil so the editor no longer arms its
own. scripts/calendar-sync-run is the batch entry point, and it blocks
until every calendar leaves the syncing state. The pipeline is asynchronous
end to end, so a batch Emacs that returns early exits zero having written
nothing.

Installing it on a machine that resolves its feeds through :secret-host
surfaced two bugs the inline-url machine could never show:

- cj/auth-source-secret-value called auth-source-search behind nothing but
  a declare-function, which quiets the compiler and loads nothing. An
  interactive Emacs always has auth-source in by the time anyone calls, so
  the omission stayed invisible until a batch -Q sync died on a void
  function. The require is guarded on fboundp. An unconditional one reloads
  auth-source over whatever is already there, which replaced a caller's
  stubbed search mid-call and sent an existing test out to the real
  authinfo.

- A synchronous failure in one calendar aborted the whole loop. The async
  callbacks record their own failures, but they never run when the error
  lands before a process starts. Resolving a :secret-host feed signals
  outright on a cold agent. Failures are contained per calendar now, so one
  bad feed no longer costs the other two.

A failed row prints the reason it recorded. Batch Emacs discards the
*Messages* buffer the interactive path logs to, so without it the journal
shows only "error", with no way to tell a cold agent from a revoked token.

12 files changed, 706 insertions, 14 deletions

diff --git a/modules/calendar-sync.el b/modules/calendar-sync.el
index d504f246..5338e7d7 100644
--- a/modules/calendar-sync.el
+++ b/modules/calendar-sync.el
@@ -87,10 +87,22 @@ calendar feed URLs."
   "Sync interval in minutes.
 Default: 60 minutes (1 hour).")
 
-(defvar calendar-sync-auto-start t
-  "Whether to automatically start calendar sync when module loads.
-If non-nil, sync starts automatically when calendar-sync is loaded.
-If nil, user must manually call `calendar-sync-start'.")
+(defvar calendar-sync-auto-start nil
+  "Whether the editor arms its own periodic sync when this module loads.
+
+Off by default: the calendar-sync.timer systemd unit owns the schedule now,
+running scripts/calendar-sync-run every ten minutes whether or not Emacs is
+up.  Leaving the in-editor timer armed as well would give two owners writing
+the same org files and the same state file, with no coordination between
+them.
+
+Set to t to hand the schedule back to the editor -- the deferred start at the
+end of this file still works, and `calendar-sync-start' and
+`calendar-sync-now' remain available on demand either way.
+
+The tradeoff this default accepts: a checkout whose timer has never been
+enabled does not sync on its own.  Enabling the unit is a one-time step per
+machine, alongside symlinking it into ~/.config/systemd/user.")
 
 (defvar calendar-sync-user-emails
   '("craigmartinjennings@gmail.com" "craig.jennings@deepsat.com" "c@cjennings.net")
@@ -215,16 +227,27 @@ calendar files do not block the interactive Emacs thread.
 
 Skips a calendar whose previous sync is still in flight, so a timer tick that
 fires before a slow fetch finishes does not launch a second overlapping sync for
-the same calendar."
+the same calendar.
+
+A synchronous failure is contained here and recorded against this calendar
+alone.  The async callbacks record their own failures, but they never run when
+the error lands before a process starts -- resolving a `:secret-host' feed
+reads authinfo.gpg, which signals outright on a cold gpg-agent.  Uncontained,
+that first error aborted the whole loop and the remaining calendars never
+synced."
   (let ((name (plist-get calendar :name)))
-    (cond
-     ((calendar-sync--syncing-p name)
-      (calendar-sync--log-silently
-       "calendar-sync: [%s] sync already in flight; skipping overlapping tick" name))
-     ((eq (plist-get calendar :fetcher) 'api)
-      (calendar-sync--sync-calendar-api calendar))
-     (t
-      (calendar-sync--sync-calendar-ics calendar)))))
+    (if (calendar-sync--syncing-p name)
+        (calendar-sync--log-silently
+         "calendar-sync: [%s] sync already in flight; skipping overlapping tick" name)
+      (condition-case err
+          (if (eq (plist-get calendar :fetcher) 'api)
+              (calendar-sync--sync-calendar-api calendar)
+            (calendar-sync--sync-calendar-ics calendar))
+        (error
+         (let ((reason (error-message-string err)))
+           (calendar-sync--log-silently
+            "calendar-sync: [%s] Sync error: %s" name reason)
+           (calendar-sync--mark-sync-failed name reason)))))))
 
 (defun calendar-sync--require-calendars ()
   "Return non-nil if calendars are configured, else warn and return nil."
@@ -297,6 +320,96 @@ When called non-interactively with nil, syncs all calendars."
       (message "calendar-sync status:\n%s"
                (string-join (nreverse status-lines) "\n")))))
 
+;;; Batch entry point
+
+;; `emacs --batch' exits the moment its top-level form returns, and this
+;; pipeline is asynchronous end to end -- curl in one process, the org
+;; conversion in a second batch Emacs.  So `calendar-sync-now' is the wrong
+;; entry point for a timer: it returns as soon as the fetches are launched,
+;; and batch Emacs would exit and kill both children mid-flight, having
+;; written nothing and reported success.
+;;
+;; The batch path therefore starts the sync and then blocks on the same
+;; per-calendar state the interactive session keeps.  Nothing new tracks
+;; completion -- the pipeline's own record of what finished is the signal.
+
+(defvar calendar-sync--batch-poll-seconds 0.2
+  "Seconds `calendar-sync--batch-wait' blocks per iteration.
+Short enough that the wait ends promptly once the last child exits, long
+enough that the loop is not a spin.  Rebound in tests.")
+
+(defvar calendar-sync-batch-timeout 300
+  "Seconds `calendar-sync-batch-run' waits for every calendar to settle.
+Covers a `calendar-sync-fetch-timeout' fetch plus the org conversion, with
+room to spare: the calendars run in parallel, so this is not a per-calendar
+budget.")
+
+(defun calendar-sync--batch-results (names)
+  "Return one (NAME . STATUS) pair per calendar in NAMES, in that order.
+A calendar with no state entry reads `never' rather than nil, so one that
+never started still counts when the failures are tallied."
+  (mapcar (lambda (name)
+            (cons name
+                  (or (plist-get (calendar-sync--get-calendar-state name) :status)
+                      'never)))
+          names))
+
+(defun calendar-sync--batch-failures (results)
+  "Return the rows of RESULTS that did not finish cleanly.
+Only `ok' passes.  `error' failed outright, `syncing' means the wait expired
+with the fetch still in flight, and `never' means the sync never started --
+in all three the org file on disk is not the calendar's current contents,
+which is the staleness the timer exists to prevent."
+  (seq-remove (lambda (row) (eq (cdr row) 'ok)) results))
+
+(defun calendar-sync--batch-wait (names timeout)
+  "Block until no calendar in NAMES is syncing, or TIMEOUT seconds elapse.
+Return non-nil when every calendar settled, nil when the timeout expired
+first.  `accept-process-output' is also what lets the fetch and conversion
+sentinels run, so this loop drives the pipeline as well as waiting on it."
+  (let ((deadline (+ (float-time) timeout)))
+    (while (and (seq-some #'calendar-sync--syncing-p names)
+                (< (float-time) deadline))
+      (accept-process-output nil calendar-sync--batch-poll-seconds))
+    (not (seq-some #'calendar-sync--syncing-p names))))
+
+;;;###autoload
+(defun calendar-sync-batch-run (&optional timeout)
+  "Sync every configured calendar, blocking until all of them finish.
+Return the (NAME . STATUS) rows.  TIMEOUT defaults to
+`calendar-sync-batch-timeout'.
+
+This is the entry point for the systemd timer.  Prefer `calendar-sync-now'
+in an interactive session, where returning immediately is the point."
+  (unless (calendar-sync--require-calendars)
+    (error "calendar-sync: no calendars configured"))
+  (let ((names (calendar-sync--calendar-names)))
+    (calendar-sync--sync-all-calendars)
+    (calendar-sync--batch-wait names (or timeout calendar-sync-batch-timeout))
+    (calendar-sync--batch-results names)))
+
+;;;###autoload
+(defun calendar-sync-batch-run-and-report ()
+  "Run a batch sync, print one line per calendar, and return an exit code.
+0 when every calendar synced, 1 otherwise.  Written for
+scripts/calendar-sync-run, which turns the code into the process's own exit
+status so systemd records a failed sync instead of swallowing it.
+
+A failed row carries its recorded `:last-error'.  The interactive failure
+path logs the reason to *Messages', which batch Emacs discards at exit, so
+without this the journal shows only `error' — no way to tell a cold
+gpg-agent from a revoked feed token or a dead network without re-running the
+sync by hand."
+  (let* ((results (calendar-sync-batch-run))
+         (failures (calendar-sync--batch-failures results)))
+    (dolist (row results)
+      (let ((reason (unless (eq (cdr row) 'ok)
+                      (plist-get (calendar-sync--get-calendar-state (car row))
+                                 :last-error))))
+        (princ (format "%s: %s%s\n" (car row) (cdr row)
+                       (if reason (format " — %s" reason) "")))))
+    (if failures 1 0)))
+
 ;;; Timer management
 
 (defun calendar-sync--sync-timer-function ()
@@ -405,6 +518,11 @@ Syncs all calendars immediately, then every `calendar-sync-interval-minutes'."
 
 ;; Defer auto-sync until calendar data is first needed.
 ;;
+;; Dormant unless `calendar-sync-auto-start' is turned back on -- the systemd
+;; timer owns the schedule now.  Kept because the reasoning below still holds
+;; for anyone who hands the schedule back to the editor, and because it is the
+;; only safe shape for an in-editor start.
+;;
 ;; The :secret-host feed URLs live in authinfo.gpg, and BOTH the immediate sync
 ;; and every periodic timer tick resolve them.  Calling `calendar-sync-start' at
 ;; load (immediate sync + recurring timer) therefore decrypts authinfo.gpg right
@@ -412,6 +530,11 @@ Syncs all calendars immediately, then every `calendar-sync-interval-minutes'."
 ;; after a reboot).  Defer the whole start to the first org-agenda use, so the
 ;; unlock happens when the user actually asks for calendar data.  A manual
 ;; `calendar-sync-start' / `calendar-sync-now' still works on demand.
+;;
+;; That deferral is also what made the timer necessary: hanging the start on
+;; `org-agenda-mode-hook' means a session where the agenda is never opened
+;; never syncs at all, which after a reboot is every session until the first
+;; agenda call.  The batch path has no such trigger to miss.
 (defun calendar-sync--auto-start-on-first-agenda ()
   "Start auto-sync on the first org-agenda use, then remove this hook.
 One-shot: deferring `calendar-sync-start' until the agenda is first built keeps a
diff --git a/modules/system-lib.el b/modules/system-lib.el
index bde53d82..c6021c9c 100644
--- a/modules/system-lib.el
+++ b/modules/system-lib.el
@@ -8,7 +8,8 @@
 ;; Eager reason: low-level helpers (executable lookup, process output, silent
 ;;   logging) used by many eager modules during startup.
 ;; Top-level side effects: none.
-;; Runtime requires: none (auth-source loaded on demand inside the helper).
+;; Runtime requires: none at load (auth-source is required on demand inside
+;; `cj/auth-source-secret-value', so the cost lands only on callers that use it).
 ;; Direct test load: yes (pure helpers; batch-safe).
 ;;
 ;; This module provides low-level system utility functions for checking
@@ -125,6 +126,19 @@ This does so without echoing in the minibuffer."
 With USER, also match on the login.  Resolves a function-valued secret
 \(the netrc backend returns the secret as a function\) by calling it.
 Callers that must have a secret layer their own error on top."
+  ;; Loaded here rather than at the top of the file, so a module that merely
+  ;; requires system-lib does not pay for auth-source.  It has to be loaded
+  ;; *somewhere*, though: `declare-function' only quiets the byte-compiler.
+  ;; An interactive Emacs always has auth-source in by the time anyone calls
+  ;; here, which hid the omission until a batch `-Q' sync tried to resolve a
+  ;; `:secret-host' feed and died on a void `auth-source-search'.
+  ;;
+  ;; Guarded on `fboundp' rather than calling `require' unconditionally: a
+  ;; bare require re-loads auth-source.el over whatever is already in place,
+  ;; which replaces a caller's stubbed `auth-source-search' mid-call and sends
+  ;; a test that meant to fake the lookup out to the real authinfo instead.
+  (unless (fboundp 'auth-source-search)
+    (require 'auth-source))
   (let* ((spec (append (list :host host :require '(:secret) :max 1)
                        (when user (list :user user))))
          (secret (plist-get (car (apply #'auth-source-search spec)) :secret)))
diff --git a/scripts/calendar-sync-run b/scripts/calendar-sync-run
new file mode 100755
index 00000000..12181b8d
--- /dev/null
+++ b/scripts/calendar-sync-run
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Sync every configured calendar from its .ics feed, once, and wait for it.
+#
+# Runs a batch Emacs rather than talking to the daemon, for the same reason
+# agenda-render-cache does: the org files this writes feed the agenda, waybar
+# and the projected wallpaper, and none of those should go stale because the
+# editor happens to be down. Nothing here touches a running Emacs, so it is
+# safe to fire from a timer alongside an active session.
+#
+# Why a script at all: calendar-sync used to start its hourly timer from
+# `org-agenda-mode-hook', so a session where the agenda was never opened never
+# synced at all. That is not a rare corner -- it is every reboot until the
+# first agenda call. The timer owns the schedule now, and the editor's own
+# auto-start is off.
+#
+# The exit code is the point. `calendar-sync-batch-run-and-report' waits for
+# every calendar to leave the syncing state and returns non-zero if any did
+# not land, so a failed fetch shows up in `systemctl --user status' instead of
+# being swallowed.
+#
+# Usage: calendar-sync-run
+# Env:   EMACS_D                -- config directory (default ~/.emacs.d)
+#        EMACS                  -- emacs binary (default emacs)
+#        CALENDAR_SYNC_CONFIG   -- private config file holding the calendar
+#                                  list, instead of the configured default.
+#        CALENDAR_SYNC_STATE    -- sync-state file, instead of the configured
+#                                  default. Lets a test run without writing
+#                                  the real session's persisted state.
+#        CALENDAR_SYNC_TIMEOUT  -- seconds to wait for all calendars to settle.
+
+set -euo pipefail
+
+EMACS_D="${EMACS_D:-$HOME/.emacs.d}"
+EMACS="${EMACS:-emacs}"
+
+if [ ! -d "$EMACS_D/modules" ]; then
+	echo "calendar-sync-run: no modules directory at $EMACS_D/modules" >&2
+	exit 1
+fi
+
+# The overrides are set before the module loads on purpose: the private config
+# is read at load time, and `defvar'/`defcustom' both leave an already-bound
+# value alone. This is the same seam the in-editor conversion worker uses.
+pre=""
+if [ -n "${CALENDAR_SYNC_CONFIG:-}" ]; then
+	pre="$pre (setq calendar-sync-private-config-file \"$CALENDAR_SYNC_CONFIG\")"
+fi
+if [ -n "${CALENDAR_SYNC_STATE:-}" ]; then
+	pre="$pre (setq calendar-sync--state-file \"$CALENDAR_SYNC_STATE\")"
+fi
+if [ -n "${CALENDAR_SYNC_TIMEOUT:-}" ]; then
+	pre="$pre (setq calendar-sync-batch-timeout $CALENDAR_SYNC_TIMEOUT)"
+fi
+
+# -Q keeps the daemon's init out of it: this needs the calendar-sync modules,
+# not a full editor. load-prefer-newer stops a stale .elc from answering for
+# changed source, which would silently sync with yesterday's logic.
+exec "$EMACS" --batch -Q \
+	--eval "(progn (setq load-prefer-newer t)$pre)" \
+	-L "$EMACS_D/modules" \
+	--eval '(progn
+                  (require (quote calendar-sync))
+                  (kill-emacs (calendar-sync-batch-run-and-report)))'
diff --git a/systemd/calendar-sync.service b/systemd/calendar-sync.service
new file mode 100644
index 00000000..0d70de57
--- /dev/null
+++ b/systemd/calendar-sync.service
@@ -0,0 +1,17 @@
+[Unit]
+Description=Sync calendars from their .ics feeds into org
+# Deliberately no dependency on emacs.service or graphical-session.target.
+# The point of moving this out of the editor is that calendars stay current
+# while Emacs is down, so the writer is a batch Emacs that needs neither the
+# daemon nor a compositor.
+Documentation=file:%h/.emacs.d/modules/calendar-sync.el
+
+[Service]
+Type=oneshot
+ExecStart=%h/.emacs.d/scripts/calendar-sync-run
+# The script waits for every calendar to settle, bounded by
+# calendar-sync-batch-timeout (300s). Cap the unit above that so the script's
+# own timeout reports a named failure per calendar, rather than systemd
+# killing it first and leaving only "timeout".
+TimeoutStartSec=360
+Nice=10
diff --git a/systemd/calendar-sync.timer b/systemd/calendar-sync.timer
new file mode 100644
index 00000000..71278f20
--- /dev/null
+++ b/systemd/calendar-sync.timer
@@ -0,0 +1,18 @@
+[Unit]
+Description=Sync calendars into org every 10 minutes
+
+[Timer]
+# OnCalendar rather than OnUnitActiveSec, because Persistent= only has an
+# effect on calendar timers (systemd.timer(5)). A monotonic schedule silently
+# ignores it, so a machine that slept through several intervals would come
+# back to stale calendar files with nothing to trigger a catch-up.
+OnCalendar=*:0/10
+Persistent=true
+# A cold boot should not wait for the next wall-clock slot. This is the case
+# the whole change exists for: before the timer, a reboot meant no calendar
+# sync at all until the agenda happened to be opened.
+OnBootSec=2min
+AccuracySec=30s
+
+[Install]
+WantedBy=timers.target
diff --git a/tests/test-calendar-sync--batch-failures.el b/tests/test-calendar-sync--batch-failures.el
new file mode 100644
index 00000000..3190be21
--- /dev/null
+++ b/tests/test-calendar-sync--batch-failures.el
@@ -0,0 +1,47 @@
+;;; test-calendar-sync--batch-failures.el --- Batch failure filter tests  -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; `calendar-sync--batch-failures' picks the rows that did not finish cleanly.
+;; The batch runner's exit code is derived from it, and systemd reads that exit
+;; code, so the rule is deliberately strict: only `ok' passes.  A calendar left
+;; `syncing' at the timeout, or one that never started, is a failure -- both
+;; states mean the org file on disk is not the calendar's current contents,
+;; which is exactly the silent staleness the timer exists to prevent.
+
+;;; Code:
+
+(require 'ert)
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'calendar-sync)
+
+(ert-deftest test-calendar-sync-batch-failures-keeps-only-non-ok ()
+  "Normal: an errored calendar is returned and a healthy one is not."
+  (should (equal (calendar-sync--batch-failures
+                  '(("google" . ok) ("proton" . error)))
+                 '(("proton" . error)))))
+
+(ert-deftest test-calendar-sync-batch-failures-all-ok-is-empty ()
+  "Normal: a fully successful run reports no failures."
+  (should (equal (calendar-sync--batch-failures
+                  '(("google" . ok) ("proton" . ok)))
+                 '())))
+
+(ert-deftest test-calendar-sync-batch-failures-empty-input-is-empty ()
+  "Boundary: no rows in, no rows out."
+  (should (equal (calendar-sync--batch-failures '()) '())))
+
+(ert-deftest test-calendar-sync-batch-failures-timeout-counts-as-failure ()
+  "Error: a calendar still `syncing' when the wait expired is a failure.
+Its org file was not rewritten, so reporting success would hide the staleness."
+  (should (equal (calendar-sync--batch-failures
+                  '(("google" . ok) ("proton" . syncing)))
+                 '(("proton" . syncing)))))
+
+(ert-deftest test-calendar-sync-batch-failures-never-counts-as-failure ()
+  "Error: a calendar that never started is a failure, not a skip."
+  (should (equal (calendar-sync--batch-failures '(("google" . never)))
+                 '(("google" . never)))))
+
+(provide 'test-calendar-sync--batch-failures)
+;;; test-calendar-sync--batch-failures.el ends here
diff --git a/tests/test-calendar-sync--batch-report.el b/tests/test-calendar-sync--batch-report.el
new file mode 100644
index 00000000..12811200
--- /dev/null
+++ b/tests/test-calendar-sync--batch-report.el
@@ -0,0 +1,89 @@
+;;; test-calendar-sync--batch-report.el --- Batch report output tests  -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; `calendar-sync-batch-run-and-report' is what the systemd timer runs, so its
+;; printed rows are the only record that survives the process.  Batch Emacs
+;; discards *Messages* at exit, which is where the interactive failure path
+;; logs its reason -- so a failed row has to carry its recorded `:last-error'
+;; in the printed output or the journal shows "error" with no way to tell a
+;; cold gpg-agent from a revoked feed token or a dead network.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)  ;; cl-letf; calendar-sync pulls it in transitively, don't rely on that
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'calendar-sync)
+
+(defun test-calendar-sync-batch-report--capture (states results)
+  "Return the report's printed output for STATES and RESULTS.
+STATES is an alist of NAME . PLIST seeded into the state table; RESULTS is
+what `calendar-sync-batch-run' is stubbed to return, so the report is
+exercised without driving a real sync."
+  (let ((calendar-sync--calendar-states (make-hash-table :test 'equal)))
+    (dolist (entry states)
+      (puthash (car entry) (cdr entry) calendar-sync--calendar-states))
+    (cl-letf (((symbol-function 'calendar-sync-batch-run)
+               (lambda (&rest _) results)))
+      (with-output-to-string
+        (calendar-sync-batch-run-and-report)))))
+
+;;; Normal
+
+(ert-deftest test-calendar-sync-batch-report-failed-row-carries-its-reason ()
+  "Normal: a failed calendar prints the recorded `:last-error' reason.
+Without it the journal records only \"error\", and the operator cannot tell a
+cold gpg-agent from a revoked token without re-running the sync by hand."
+  (let ((out (test-calendar-sync-batch-report--capture
+              '(("google" . (:status error :last-error "Decryption failed"))
+                ("proton" . (:status ok)))
+              '(("google" . error) ("proton" . ok)))))
+    (should (string-match-p "google: error" out))
+    (should (string-match-p "Decryption failed" out))))
+
+(ert-deftest test-calendar-sync-batch-report-ok-row-stays-bare ()
+  "Normal: a calendar that synced prints its status and nothing more.
+A stale `:last-error' from an earlier failure must not be appended to a row
+that succeeded this run."
+  (let ((out (test-calendar-sync-batch-report--capture
+              '(("google" . (:status ok :last-error "Decryption failed")))
+              '(("google" . ok)))))
+    (should (string-match-p "google: ok" out))
+    (should-not (string-match-p "Decryption failed" out))))
+
+;;; Boundary
+
+(ert-deftest test-calendar-sync-batch-report-failure-without-reason-still-prints ()
+  "Boundary: a failed row with no recorded reason prints its status alone.
+`never' and `syncing' never record a `:last-error', so the reason lookup has
+to tolerate nil rather than printing \"nil\" or signalling."
+  (let ((out (test-calendar-sync-batch-report--capture
+              '(("google" . (:status syncing)))
+              '(("google" . syncing) ("absent" . never)))))
+    (should (string-match-p "google: syncing" out))
+    (should (string-match-p "absent: never" out))
+    (should-not (string-match-p "nil" out))))
+
+;;; Error
+
+(defun test-calendar-sync-batch-report--exit-code (results)
+  "Return the report's exit code for RESULTS, discarding its printed output."
+  (let ((calendar-sync--calendar-states (make-hash-table :test 'equal)))
+    (cl-letf (((symbol-function 'calendar-sync-batch-run)
+               (lambda (&rest _) results)))
+      (with-temp-buffer
+        (let ((standard-output (current-buffer)))
+          (calendar-sync-batch-run-and-report))))))
+
+(ert-deftest test-calendar-sync-batch-report-exit-code-tracks-failures ()
+  "Error: the return value becomes the process exit code, so it stays 1 on any
+non-ok row and 0 only when every calendar synced.  Appending the reason to the
+printed line must not disturb it."
+  (should (equal 1 (test-calendar-sync-batch-report--exit-code '(("google" . error)))))
+  (should (equal 1 (test-calendar-sync-batch-report--exit-code
+                    '(("google" . ok) ("proton" . never)))))
+  (should (equal 0 (test-calendar-sync-batch-report--exit-code '(("google" . ok))))))
+
+(provide 'test-calendar-sync--batch-report)
+;;; test-calendar-sync--batch-report.el ends here
diff --git a/tests/test-calendar-sync--batch-results.el b/tests/test-calendar-sync--batch-results.el
new file mode 100644
index 00000000..03ee2aee
--- /dev/null
+++ b/tests/test-calendar-sync--batch-results.el
@@ -0,0 +1,59 @@
+;;; test-calendar-sync--batch-results.el --- Batch result collection tests  -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; `calendar-sync--batch-results' reads the per-calendar state table and
+;; returns one (NAME . STATUS) pair per requested calendar.  The batch runner
+;; turns that into an exit code, so a calendar that never reached the table at
+;; all has to read as `never' rather than nil -- a nil status would compare
+;; equal to nothing and quietly drop out of the failure count.
+
+;;; Code:
+
+(require 'ert)
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'calendar-sync)
+
+(defun test-calendar-sync-batch-results--with-states (states body)
+  "Run BODY with STATES (an alist of NAME . PLIST) in the state table."
+  (let ((calendar-sync--calendar-states (make-hash-table :test 'equal)))
+    (dolist (entry states)
+      (puthash (car entry) (cdr entry) calendar-sync--calendar-states))
+    (funcall body)))
+
+(ert-deftest test-calendar-sync-batch-results-reports-each-status ()
+  "Normal: every requested calendar comes back with its recorded status."
+  (test-calendar-sync-batch-results--with-states
+   '(("google" . (:status ok))
+     ("proton" . (:status error :last-error "boom")))
+   (lambda ()
+     (should (equal (calendar-sync--batch-results '("google" "proton"))
+                    '(("google" . ok) ("proton" . error)))))))
+
+(ert-deftest test-calendar-sync-batch-results-empty-names-is-empty ()
+  "Boundary: no calendars requested yields no rows, not an error."
+  (test-calendar-sync-batch-results--with-states
+   '(("google" . (:status ok)))
+   (lambda ()
+     (should (equal (calendar-sync--batch-results '()) '())))))
+
+(ert-deftest test-calendar-sync-batch-results-missing-calendar-reads-never ()
+  "Error: a calendar absent from the state table reads `never', never nil.
+A nil status would drop out of the failure count and report success for a
+calendar that never ran."
+  (test-calendar-sync-batch-results--with-states
+   '(("google" . (:status ok)))
+   (lambda ()
+     (should (equal (calendar-sync--batch-results '("google" "absent"))
+                    '(("google" . ok) ("absent" . never)))))))
+
+(ert-deftest test-calendar-sync-batch-results-preserves-request-order ()
+  "Boundary: rows come back in the order asked for, not hash order."
+  (test-calendar-sync-batch-results--with-states
+   '(("a" . (:status ok)) ("b" . (:status ok)) ("c" . (:status ok)))
+   (lambda ()
+     (should (equal (mapcar #'car (calendar-sync--batch-results '("c" "a" "b")))
+                    '("c" "a" "b"))))))
+
+(provide 'test-calendar-sync--batch-results)
+;;; test-calendar-sync--batch-results.el ends here
diff --git a/tests/test-calendar-sync--batch-wait.el b/tests/test-calendar-sync--batch-wait.el
new file mode 100644
index 00000000..7deee5e1
--- /dev/null
+++ b/tests/test-calendar-sync--batch-wait.el
@@ -0,0 +1,68 @@
+;;; test-calendar-sync--batch-wait.el --- Batch wait-loop tests  -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; The sync pipeline is asynchronous end to end: curl runs in one process and
+;; the org conversion in a second batch Emacs.  Under `emacs --batch' the
+;; process exits as soon as the top-level form returns, killing both children
+;; mid-flight -- a run that does nothing and reports success.
+;;
+;; `calendar-sync--batch-wait' is what stops that: it blocks until every
+;; calendar has left the `syncing' state, or until the timeout expires.  These
+;; tests drive it with a stubbed state predicate, so the loop's exit conditions
+;; are covered without a live network fetch.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'calendar-sync)
+
+(ert-deftest test-calendar-sync-batch-wait-returns-when-nothing-in-flight ()
+  "Normal: with no calendar syncing the wait returns success immediately."
+  (let ((polls 0))
+    (cl-letf (((symbol-function 'calendar-sync--syncing-p) (lambda (_) nil))
+              ((symbol-function 'accept-process-output)
+               (lambda (&rest _) (setq polls (1+ polls)))))
+      (should (calendar-sync--batch-wait '("google" "proton") 5))
+      (should (= polls 0)))))
+
+(ert-deftest test-calendar-sync-batch-wait-blocks-until-settled ()
+  "Normal: the wait polls while a sync is in flight and returns once it lands."
+  (let ((remaining 3)
+        (polls 0))
+    (cl-letf (((symbol-function 'calendar-sync--syncing-p)
+               (lambda (_) (> remaining 0)))
+              ((symbol-function 'accept-process-output)
+               (lambda (&rest _)
+                 (setq polls (1+ polls))
+                 (setq remaining (1- remaining)))))
+      (should (calendar-sync--batch-wait '("google") 5))
+      (should (= polls 3)))))
+
+(ert-deftest test-calendar-sync-batch-wait-empty-names-returns-immediately ()
+  "Boundary: no calendars to wait on settles at once."
+  (let ((polls 0))
+    (cl-letf (((symbol-function 'accept-process-output)
+               (lambda (&rest _) (setq polls (1+ polls)))))
+      (should (calendar-sync--batch-wait '() 5))
+      (should (= polls 0)))))
+
+(ert-deftest test-calendar-sync-batch-wait-times-out-when-stuck ()
+  "Error: a sync that never settles returns nil once the timeout expires.
+Returning nil is what lets the runner exit non-zero instead of reporting a
+success it cannot vouch for."
+  (let ((calendar-sync--batch-poll-seconds 0.01))
+    (cl-letf (((symbol-function 'calendar-sync--syncing-p) (lambda (_) t))
+              ((symbol-function 'accept-process-output) (lambda (&rest _) nil)))
+      (should-not (calendar-sync--batch-wait '("google") 0.05)))))
+
+(ert-deftest test-calendar-sync-batch-wait-zero-timeout-does-not-hang ()
+  "Boundary: a zero timeout returns at once rather than looping forever."
+  (cl-letf (((symbol-function 'calendar-sync--syncing-p) (lambda (_) t))
+            ((symbol-function 'accept-process-output) (lambda (&rest _) nil)))
+    (should-not (calendar-sync--batch-wait '("google") 0))))
+
+(provide 'test-calendar-sync--batch-wait)
+;;; test-calendar-sync--batch-wait.el ends here
diff --git a/tests/test-calendar-sync--sync-dispatch.el b/tests/test-calendar-sync--sync-dispatch.el
index 22deeef0..9b12b167 100644
--- a/tests/test-calendar-sync--sync-dispatch.el
+++ b/tests/test-calendar-sync--sync-dispatch.el
@@ -77,5 +77,44 @@ than crashing."
       (should (equal (list cal) ics-calls))
       (should (null api-calls)))))
 
+(ert-deftest test-calendar-sync--sync-dispatch-error-leaf-signal-is-contained ()
+  "Error: a syncer that signals marks the calendar failed instead of propagating.
+
+Resolving a `:secret-host' feed reads authinfo.gpg, and a cold gpg-agent makes
+that signal a `file-error' before any process starts — so the failure arrives
+synchronously, where the async callbacks that normally record a failure never
+run."
+  (let ((failed '())
+        (calendar-sync--calendar-states (make-hash-table :test 'equal)))
+    (cl-letf (((symbol-function 'calendar-sync--sync-calendar-ics)
+               (lambda (_) (signal 'file-error '("Decryption failed"))))
+              ((symbol-function 'calendar-sync--mark-sync-failed)
+               (lambda (name reason) (push (cons name reason) failed))))
+      (calendar-sync--sync-calendar
+       '(:name "google" :url "https://x/y.ics" :file "/tmp/c.org"))
+      (should (equal "google" (car (car failed)))))))
+
+(ert-deftest test-calendar-sync--sync-all-continues-past-a-failing-calendar ()
+  "Error: one calendar's synchronous failure does not stop the ones after it.
+
+This is the whole cost of leaving the signal uncontained: on a machine whose
+feeds resolve through authinfo, the first calendar's decryption error aborted
+the entire run, so calendars that would have synced fine never got the chance."
+  (let ((synced '())
+        (calendar-sync--calendar-states (make-hash-table :test 'equal))
+        (calendar-sync-calendars
+         '((:name "bad" :url "https://x/a.ics" :file "/tmp/a.org")
+           (:name "good" :url "https://x/b.ics" :file "/tmp/b.org"))))
+    (cl-letf (((symbol-function 'calendar-sync--sync-calendar-ics)
+               (lambda (cal)
+                 (if (equal (plist-get cal :name) "bad")
+                     (signal 'file-error '("Decryption failed"))
+                   (push (plist-get cal :name) synced))))
+              ((symbol-function 'calendar-sync--mark-sync-failed)
+               (lambda (&rest _) nil))
+              ((symbol-function 'message) (lambda (&rest _) nil)))
+      (calendar-sync--sync-all-calendars)
+      (should (equal '("good") synced)))))
+
 (provide 'test-calendar-sync--sync-dispatch)
 ;;; test-calendar-sync--sync-dispatch.el ends here
diff --git a/tests/test-calendar-sync-run.bats b/tests/test-calendar-sync-run.bats
new file mode 100644
index 00000000..da817060
--- /dev/null
+++ b/tests/test-calendar-sync-run.bats
@@ -0,0 +1,116 @@
+#!/usr/bin/env bats
+# Tests for scripts/calendar-sync-run — the batch syncer behind the timer.
+#
+# The elisp tests cover the wait loop and the result tally with the state
+# predicate stubbed.  What only a shell test can cover is the thing that makes
+# the whole script necessary: the sync pipeline is asynchronous end to end
+# (curl in one process, the org conversion in a second batch Emacs), and a
+# batch Emacs exits as soon as its top-level form returns.  A version that
+# launches the fetch and returns would exit zero, write nothing, and look
+# exactly like a success.  Every assertion here that checks the output file
+# exists is really asserting that the script waited.
+#
+# Isolation rules, mirroring test-agenda-render-cache.bats:
+#
+#   EMACS_D points at THIS checkout, so a broken tree cannot pass by running
+#   the installed config's elisp.
+#
+#   CALENDAR_SYNC_CONFIG and CALENDAR_SYNC_STATE point at fixtures, so the run
+#   neither reads Craig's real feed URLs nor writes his persisted sync state.
+#
+#   The feed is a file:// URL served to the script's own curl.  That keeps the
+#   test hermetic -- no network, no live calendar -- while still exercising the
+#   real fetch path rather than a stub.
+
+setup() {
+	SCRIPT="${BATS_TEST_DIRNAME}/../scripts/calendar-sync-run"
+	export EMACS_D="${BATS_TEST_DIRNAME}/.."
+	export CALENDAR_SYNC_STATE="${BATS_TEST_TMPDIR}/state.el"
+	export CALENDAR_SYNC_TIMEOUT=120
+
+	OUT="${BATS_TEST_TMPDIR}/testcal.org"
+	ICS="${BATS_TEST_TMPDIR}/feed.ics"
+	TODAY="$(date +%Y%m%d)"
+
+	cat > "$ICS" <<-EOF
+		BEGIN:VCALENDAR
+		VERSION:2.0
+		PRODID:-//bats//test//EN
+		BEGIN:VEVENT
+		UID:bats-fixture-1
+		DTSTART:${TODAY}T140000Z
+		DTEND:${TODAY}T150000Z
+		SUMMARY:Batch Fixture Event
+		END:VEVENT
+		END:VCALENDAR
+	EOF
+
+	write_config "file://${ICS}"
+}
+
+# The calendar list is normally private config; the test writes its own so the
+# feed URL is a local file and the output lands in the temp dir.
+write_config() {
+	export CALENDAR_SYNC_CONFIG="${BATS_TEST_TMPDIR}/config.el"
+	cat > "$CALENDAR_SYNC_CONFIG" <<-EOF
+		(setq calendar-sync-calendars
+		      (list (list :name "testcal" :url "$1" :file "${OUT}")))
+	EOF
+}
+
+@test "the script is executable" {
+	[ -x "$SCRIPT" ]
+}
+
+@test "waits for the async pipeline and writes the org file" {
+	run "$SCRIPT"
+	[ "$status" -eq 0 ]
+	# The file existing at all is the assertion: it is written by a grandchild
+	# process, so a script that did not wait would have exited before this.
+	[ -f "$OUT" ]
+	grep -q "Batch Fixture Event" "$OUT"
+}
+
+@test "reports the calendar and its status on stdout" {
+	run "$SCRIPT"
+	[ "$status" -eq 0 ]
+	[[ "$output" == *"testcal: ok"* ]]
+}
+
+@test "a failed fetch exits non-zero so systemd records it" {
+	write_config "file://${BATS_TEST_TMPDIR}/does-not-exist.ics"
+	run "$SCRIPT"
+	[ "$status" -ne 0 ]
+	[ ! -f "$OUT" ]
+}
+
+@test "a failed fetch names the calendar rather than failing silently" {
+	write_config "file://${BATS_TEST_TMPDIR}/does-not-exist.ics"
+	run "$SCRIPT"
+	[[ "$output" == *"testcal"* ]]
+	[[ "$output" != *"testcal: ok"* ]]
+}
+
+@test "a failed fetch prints why, not just that it failed" {
+	# The interactive path logs the reason to *Messages*, which batch Emacs
+	# discards at exit.  Without the reason on stdout the journal shows only
+	# "error" -- no way to tell a cold gpg-agent from a revoked feed token.
+	write_config "file://${BATS_TEST_TMPDIR}/does-not-exist.ics"
+	run "$SCRIPT"
+	[[ "$output" == *"testcal: error"* ]]
+	[[ "$output" == *"Fetch failed"* ]]
+}
+
+@test "refuses to run against a checkout with no modules directory" {
+	EMACS_D="${BATS_TEST_TMPDIR}/empty" run "$SCRIPT"
+	[ "$status" -ne 0 ]
+	[[ "$output" == *"no modules directory"* ]]
+}
+
+@test "does not write the real session's sync state" {
+	run "$SCRIPT"
+	[ "$status" -eq 0 ]
+	# The state override is honoured, so a timer run cannot corrupt or race
+	# the interactive session's persisted state.
+	[ -f "$CALENDAR_SYNC_STATE" ]
+}
diff --git a/tests/test-system-lib-auth-source-secret-value.el b/tests/test-system-lib-auth-source-secret-value.el
index ec526cec..27a2696b 100644
--- a/tests/test-system-lib-auth-source-secret-value.el
+++ b/tests/test-system-lib-auth-source-secret-value.el
@@ -63,5 +63,44 @@ Captures the call args in `test-ass--args'."
   (test-ass--with-search (list (list :host "h"))
     (should (null (cj/auth-source-secret-value "h")))))
 
+;;; Error
+
+(ert-deftest test-auth-source-secret-value-loads-auth-source-when-absent ()
+  "Error: with `auth-source-search' unavailable, the helper loads auth-source.
+
+Under `emacs --batch -Q' nothing else pulls auth-source in, so a helper
+carrying only a `declare-function' dies with a void-function on the first
+lookup.  An interactive Emacs hides this completely -- something in init
+always has auth-source loaded by the time anyone calls here -- which is why
+it surfaced only on the batch calendar sync, and only on the machine whose
+feeds resolve through `:secret-host' rather than an inline URL.
+
+The stubbed `require' installs the entry point the way loading auth-source.el
+would, so the call can complete and the return value is checked too."
+  (let ((required nil))
+    (cl-letf (((symbol-function 'auth-source-search) nil)
+              ((symbol-function 'require)
+               (lambda (feature &rest _)
+                 (push feature required)
+                 (fset 'auth-source-search
+                       (lambda (&rest _) (list (list :secret "loaded"))))
+                 feature)))
+      (should (equal "loaded" (cj/auth-source-secret-value "h")))
+      (should (memq 'auth-source required)))))
+
+(ert-deftest test-auth-source-secret-value-does-not-reload-when-present ()
+  "Error: an available `auth-source-search' is used as-is, never re-required.
+
+An unconditional `require' re-loads auth-source.el over whatever is in place,
+replacing a caller's stub mid-call -- which sent a test that meant to fake the
+lookup out to the real authinfo, where it hung for twelve seconds on gpg."
+  (let ((required nil))
+    (cl-letf (((symbol-function 'require)
+               (lambda (feature &rest _) (push feature required) feature))
+              ((symbol-function 'auth-source-search)
+               (lambda (&rest _) (list (list :secret "stubbed")))))
+      (should (equal "stubbed" (cj/auth-source-secret-value "h")))
+      (should-not (memq 'auth-source required)))))
+
 (provide 'test-system-lib-auth-source-secret-value)
 ;;; test-system-lib-auth-source-secret-value.el ends here