[torlando-tech]

Summary

Fixes the NomadNet UI freeze where opening any page hung forever on "Checking SD page cache...".

The SD page cache (16af3b5, Aug 17) made the SD card a soft dependency of page
loads for the first time. NomadNetCache retries transient SD storage results
(BUSY = SPI-mutex timeout, UNAVAILABLE = card not mounted) with no budget or
deadline: every step treats them as "retry next tick" forever. Because
NomadNetCacheFlow::service() early-returns while cache_.busy() and the UI's
NomadState::CACHE has no timeout, a persistently-unhealthy SD seam pins the UI
in "Checking SD page cache..." indefinitely.

Fix

NomadNetCache::service() now detects no-progress ticks across consecutive
calls: if this call's entry state (op, offset, scan/cleanup index, scan count,
open-flags) is identical to the previous call's, a counter increments; any real
advance resets it. After MAX_TRANSIENT_STALL_TICKS (500 — far beyond any real
SPI contention or mount window, and safe for legitimate multi-tick steps like
64 KB chunked commits and 96-record recovery scans) it bails:

• clears the in-flight operation (operation_ = NONE), and
• marks the namespace non-authoritative for the session (recovery_complete_ = false), so subsequent beginLookup() calls return BYPASS.

The flow then drops to NEED_LIVE and does a live fetch — the pre-cache
behavior. No data is wiped; a healthy SD later in the session simply means no
cache benefit for that boot. The cache becomes a no-op rather than a freeze.

Verification

• RED→GREEN: new regression tests fail on origin/main and pass with the fix.
  • test_nomadnet_cache.cpp: persistent UNAVAILABLE at boot and persistent
    BUSY at boot both bail in bounded ticks and mark the namespace
    non-authoritative; a mid-transfer commit stall bails and reports.
  • test_nomadnet_cache_flow.cpp: drives the real NomadNetCacheFlow with a
    BusyListStorage mock — asserts the flow reaches NEED_LIVE (not stuck in
    LOOKUP) in bounded service ticks (the exact UI symptom).
• tdeck firmware: build SUCCESS (23.2% RAM, 92.9% flash).
• tests/native: 121 passed; tests/build_scripts: 184 passed. (3 pre-existing
  env failures — nomadnet_x86_flow, 2 lvgl_dependency — fail identically on
  the origin/main baseline, not regressions.)
• Physical (T-Deck): app-only flash of 0.3.8-39-gfeb7f05, all partitions
  preserved (NVS/LittleFS/identity/otadata/coredump), app0 read-back verified
  sha256. Device boots clean; a NomadNet page loads (first request needed a
  second attempt — live-fetch fallback is working as designed).

Test Plan

• pio run -e tdeck builds clean
• pytest tests/native/test_nomadnet_cache.py test_nomadnet_cache_flow.py test_nomadnet_storage.py pass (RED on main, GREEN with fix)
• Physical: NomadNet page loads on T-Deck; no permanent "Checking SD page cache..." freeze

Closes the NomadNet page-cache UI freeze.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the previous findings are resolved and no new actionable failure was identified.

Summary

The PR prevents persistent transient SD-card failures from indefinitely blocking NomadNet page loading.

• Adds tick- and elapsed-time-based detection for cache operations that make no progress.
• Abandons stalled cache operations, releases in-flight storage resources on a best-effort basis, and falls back to live page retrieval.
• Handles Arduino millis() rollover with wrap-safe elapsed-time arithmetic.
• Adds cache- and flow-level regression coverage for persistent stalls, recovery, reload invalidation, resource cleanup, and clock rollover.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[NomadNet cache operation] --> B{State progressed?}
    B -- Yes --> C[Reset stall counter]
    B -- No --> D[Increment stall counter]
    D --> E{Tick floor and 10 seconds elapsed?}
    E -- No --> A
    E -- Yes --> F[Best-effort resource cleanup]
    F --> G[Mark namespace non-authoritative]
    G --> H[Clear cache operation with MISS]
    H --> I[Flow transitions to NEED_LIVE]
    I --> J[Fetch page live]

Loading

_{Reviews (3) · Last reviewed commit: "fix(nomadnet): make the transient-stall ..."}