Correct the described failure window of a naive millis() compare

The comments and agent docs said a bare `millis() > deadline` "breaks for ~24
days after the wrap". That figure belongs to the fix, not the bug: it is the
half-range limit of deadlinePassed(), which reads deadlines more than 2^31 ms
ahead as already passed, and the range over which a UINT32_MAX sentinel reads
as passed.

The naive compare's actual failure is an inversion lasting only while the
deadline sits on the far side of the wrap, so it is bounded by the interval:
the action fires immediately and loses its wait, or blocks for about the wait
it should have performed - days for the nRF52 flash-corruption backoff,
one skipped cycle for a seconds-long retransmit timer.

Comments and docs only; the ~24.8 day statements that correctly describe
deadlinePassed()'s own range are left as they were.

clod helped out here

Author: NomDeTom

.github/copilot-instructions.md

@@ -343,7 +343,7 @@ firmware/
   - `Throttle::deadlinePassed(deadlineMs)` - for a stored absolute deadline that cannot be re-expressed as "interval since an event". Uses an unsigned half-range compare; reads deadlines more than ~24.8 days out as already passed, which no interval in this firmware approaches (the longest is 24 h).
   - `Throttle::deadlinePassedAt(nowMs, deadlineMs)` - the same test against a caller-supplied `now`, for a loop that snapshots the clock once and then tests many deadlines (`NextHopRouter::doRetransmissions()`). Take the snapshot from `Time::getMillis()`, not `millis()`.
 
-  Raw `millis() > deadline` or `deadline < millis()` is rollover-unsafe: for ~24 days after the 32-bit wrap it either stalls the action or fires it immediately. All five helpers subtract first, so unsigned wraparound cancels out. `Throttle` reads the clock through `Time::getMillis()` (`src/UptimeClock.h`), which means every one of its ~94 call sites is time-injectable - a native test can drive `Time::setTestMillis(0xFFFFFF00)` across the wrap. There is deliberately no 64-bit millis; see the note in `UptimeClock.h`.
+  Raw `millis() > deadline` or `deadline < millis()` is rollover-unsafe: the comparison inverts while the deadline sits on the far side of the 32-bit wrap, so the action fires immediately (losing its whole wait) or blocks for roughly the interval it should have waited - days, for the nRF52 flash-corruption backoff. All five helpers subtract first, so unsigned wraparound cancels out. `Throttle` reads the clock through `Time::getMillis()` (`src/UptimeClock.h`), which means every one of its ~94 call sites is time-injectable - a native test can drive `Time::setTestMillis(0xFFFFFF00)` across the wrap. There is deliberately no 64-bit millis; see the note in `UptimeClock.h`.
 
   **Sentinel hazard.** If a deadline variable also encodes "inactive" - `0` for `rebootAtMsec`, `shutdownAtMsec`, `alertBannerUntil`, `fixHoldEnds`; `UINT32_MAX` for `nagCycleCutoff` - test that sentinel _before_ the elapsed comparison. Every such value is arithmetically far in the past, so a correct comparison reads it as "expired" and fires immediately: `rebootAtMsec = -1` meaning "never" is what would have become a reboot loop. Write `if (deadline && Throttle::deadlinePassed(deadline))`, and never fold the sentinel into the helper.
 

.github/millis-deadline-allowlist.txt

@@ -1,7 +1,7 @@
 # Allowlist for the millis-deadline-check guard in .github/workflows/test_native.yml.
 #
-# That guard rejects comparisons made directly against millis(), because they break for ~24 days
-# after the 32-bit wrap. Use Throttle::deadlinePassed(deadline) or
+# That guard rejects comparisons made directly against millis(), because they invert while the
+# deadline sits on the far side of the 32-bit wrap. Use Throttle::deadlinePassed(deadline) or
 # Throttle::hasElapsed(lastEvent, intervalMs) instead - see .github/copilot-instructions.md.
 #
 # Only add a line here when the comparison genuinely is not a deadline test. The usual valid case is

.github/workflows/test_native.yml

@@ -55,8 +55,9 @@ jobs:
           echo "native-suite-count matches the $expected_count suite directories."
 
   # Reject naive deadline comparisons against millis(). `millis() > deadline` and
-  # `deadline < millis()` are wrong for ~24 days after the 32-bit millis() wrap: depending on which
-  # side wrapped they either stall the action or fire it immediately. The correct forms are
+  # `deadline < millis()` invert while the deadline sits on the far side of the 32-bit wrap: the
+  # action fires immediately, or blocks for about the interval it should have waited. The correct
+  # forms are
   # Throttle::isWithinTimespanMs / hasElapsed (elapsed since a stored event) and
   # Throttle::deadlinePassed (an absolute deadline). See .github/copilot-instructions.md.
   millis-deadline-check:
@@ -113,7 +114,7 @@ jobs:
           done < /tmp/millis-hits.tsv
 
           if [[ $violations -gt 0 ]]; then
-            echo "::error title=Naive millis() deadline compare::$violations line(s) compare against millis() directly, which breaks for ~24 days after the 32-bit wrap - the action either stalls or fires immediately. Use Throttle::deadlinePassed(deadline) for a stored absolute deadline, or Throttle::hasElapsed(lastEvent, intervalMs) for an interval. If a match genuinely is not a deadline test (an uptime threshold, say), add it to $allowlist with a reason."
+            echo "::error title=Naive millis() deadline compare::$violations line(s) compare against millis() directly, which inverts while the deadline is on the far side of the 32-bit wrap - the action fires immediately, or blocks for about the interval it should have waited. Use Throttle::deadlinePassed(deadline) for a stored absolute deadline, or Throttle::hasElapsed(lastEvent, intervalMs) for an interval. If a match genuinely is not a deadline test (an uptime threshold, say), add it to $allowlist with a reason."
             exit 1
           fi
           echo "No naive millis() deadline comparisons in src/ (allowlist: $(wc -l < /tmp/millis-allowed.tsv) entr(y/ies))."

AGENTS.md

@@ -88,7 +88,7 @@ Key rotation to never trigger casually: only the **full** factory reset (`factor
   - `Throttle::deadlinePassed(deadlineMs)` - for a stored absolute deadline that cannot be re-expressed as "interval since an event".
   - `Throttle::deadlinePassedAt(nowMs, deadlineMs)` - the same test against a caller-supplied `now`, for a loop that snapshots the clock once and tests many deadlines. Snapshot from `Time::getMillis()`.
 
-  Raw `millis() > deadline` or `deadline < millis()` is rollover-unsafe: for ~24 days after the 32-bit wrap it either stalls the action or fires it immediately. All five helpers subtract first, so unsigned wraparound cancels out. `Throttle` reads the clock through `Time::getMillis()` (`src/UptimeClock.h`), so all ~94 of its call sites are time-injectable and a native test can drive the wrap with `Time::setTestMillis()`.
+  Raw `millis() > deadline` or `deadline < millis()` is rollover-unsafe: the comparison inverts while the deadline sits on the far side of the 32-bit wrap, so the action fires immediately or blocks for roughly the interval it should have waited. All five helpers subtract first, so unsigned wraparound cancels out. `Throttle` reads the clock through `Time::getMillis()` (`src/UptimeClock.h`), so all ~94 of its call sites are time-injectable and a native test can drive the wrap with `Time::setTestMillis()`.
 
   **Sentinel hazard.** If a deadline variable also encodes "inactive" (`0` for `rebootAtMsec`, `shutdownAtMsec`, `alertBannerUntil`, `fixHoldEnds`; `UINT32_MAX` for `nagCycleCutoff`), test that sentinel _before_ the elapsed comparison - every such value is arithmetically far in the past, so a correct comparison fires on it immediately. Write `if (deadline && Throttle::deadlinePassed(deadline))`.
 

src/mesh/Throttle.h

@@ -18,8 +18,8 @@ class Throttle
     }
 
     /// True once an absolute deadline has arrived. Use this rather than comparing against millis()
-    /// directly, which breaks for ~24 days after the 32-bit wrap - either stalling the action or
-    /// firing it immediately, depending on which side wrapped.
+    /// directly: that inverts while the deadline sits on the far side of the 32-bit wrap, so the
+    /// action either fires immediately or blocks for about the interval it should have waited.
     ///
     /// Use this when the site stores a deadline; use hasElapsed() when it stores the time of the
     /// last event, which allows the full ~49.7 day range instead of ~24.8 days ahead.