docs: document chime-async-timeout and the frozen-modeline symptom

2 files changed, 36 insertions, 0 deletions

diff --git a/docs/CONFIGURATION.org b/docs/CONFIGURATION.org
index 87ff0cf..a6dc979 100644
--- a/docs/CONFIGURATION.org
+++ b/docs/CONFIGURATION.org
@@ -383,6 +383,25 @@ Today's events always show if you launch Emacs after the alert time. This settin
 (setq chime-max-consecutive-failures 0)
 #+END_SRC
 
+** Async Fetch Timeout
+
+Event fetching runs in a background Emacs process. If that process never
+returns — for example, it hits an interactive prompt that batch mode can't
+answer — chime interrupts it after =chime-async-timeout= seconds, records
+the failure, and starts a fresh fetch on the next check. Without this
+watchdog, a hung fetch would silently block every subsequent check.
+
+#+BEGIN_SRC elisp
+;; Interrupt a fetch that runs longer than 2 minutes (default)
+(setq chime-async-timeout 120)
+
+;; Allow slower agenda scans more time
+(setq chime-async-timeout 300)
+
+;; Disable the watchdog entirely
+(setq chime-async-timeout nil)
+#+END_SRC
+
 ** Extra Alert Arguments
 
 #+BEGIN_SRC elisp
diff --git a/docs/TROUBLESHOOTING.org b/docs/TROUBLESHOOTING.org
index 5f28a5c..b1fadde 100644
--- a/docs/TROUBLESHOOTING.org
+++ b/docs/TROUBLESHOOTING.org
@@ -178,3 +178,20 @@ For custom predicate functions, ensure any variables they depend on are availabl
 #+BEGIN_SRC elisp
 (setq chime-additional-environment-regexes '("my-custom-var"))
 #+END_SRC
+
+* Modeline Frozen on a Stale Countdown
+
+If the modeline shows a countdown that never advances past an old event,
+the background fetch process likely hung, blocking every later check.
+Chime's watchdog interrupts a fetch after =chime-async-timeout= seconds
+(default 120) and logs "Async watchdog" to =*Messages*=, so a hang heals
+itself within one timeout plus one check interval.
+
+If you see repeated "Async watchdog" log lines, something in the fetch is
+consistently hanging or too slow:
+
+- A very large agenda can legitimately exceed the timeout — raise it:
+  =(setq chime-async-timeout 300)=
+- An entry in =org-agenda-files= pointing at a deleted file used to hang
+  the fetch on org's recovery prompt; chime now skips missing files, but
+  cleaning up stale entries keeps the agenda scan honest.