Advanced Scan Settings — Slice 3: active SMART piggyback on spin-up events (needs grilling)

[mcdays94]

Parent PRD

#236

Status

Tracker issue — implementation not yet designed. Placeholder for slice 3 of the Advanced Scan Settings rework. Before implementation tickets can be created, slice 3 needs its own grilling session (grill-me → design-an-interface for platform-specific drive-state detection → prd-to-issues).

What this slice will deliver

Active SMART piggyback. Rather than relying on -n standby passively (which reads SMART only when drives happen to be awake) plus slice 1's max-age safety net (which forces a wake if too much time passes), slice 3 adds an active detection layer: NAS Doctor notices when drives are already awake (parity check in progress, recent filesystem I/O on the drive, etc.) and opportunistically runs SMART in that window. Strongest guarantee of routine fresh SMART data without extra wear cost.

High-level scope from PRD #236:

• Platform-specific drive-awake detection:
  • Unraid: parse parity-check state from /var/local/emhttp
  • Generic Linux: /proc/diskstats deltas to detect recent I/O per drive
  • sysfs polling for drive power state where available
• New toggle under Settings.AdvancedScans.SMART: PiggybackOnSpinUps bool
• Integration with ScanDispatcher (slice 2) and StaleSMARTChecker (slice 1) — piggyback events take precedence over the max-age force-wake path because the drive is already awake
• Graceful fallback on non-Unraid platforms where detection primitives aren't available

User stories this will address

Reference by number from parent PRD #236: user stories 19-21.

Open design questions for grilling

• Detection mechanism per platform — what primitives does each support?
• Detection cadence — how often do we poll for drive-awake state?
• Debouncing — how long after the drive goes to sleep is it "no longer awake" for purposes of piggyback?
• Interaction with max-age (slice 1) — do piggyback runs reset the max-age timer?
• Interaction with ScanDispatcher (slice 2) — is piggyback an interrupt that runs outside the scheduled interval, or a hook that replaces the scheduled run?
• UI — a simple toggle, or does it need inline explanation of what "active piggyback" means?
• Observability — do we log every piggyback run? Only the first per day? None?
• Fleet implications — local-only per-instance (consistent with slices 1 and 2)

Why this might not actually be needed

Worth revisiting during grilling: slice 1's max-age fallback may cover 90% of slice 3's value proposition by ensuring SMART runs at least every N days. Active piggyback adds a stronger guarantee ("runs whenever drives happen to be awake") but with high engineering cost (platform-specific detection is a rabbit hole). This slice may be deferred indefinitely based on user feedback after slice 1 ships.

Blocked by

• Blocked by Advanced Scan Settings: SMART max-age force-wake behaviour (end-to-end) #238 (V1b, slice 1 activation) — we need real-world feedback on whether max-age alone is sufficient before committing to slice 3
• Very likely blocked by the slice-2 implementation — piggyback is most cleanly expressed as a hook on ScanDispatcher, which slice 2 introduces
• Also gated on its own grilling session before any implementation tickets are filed

Next step

Defer until after slice 1 ships and user feedback is gathered. When ready: grill-me on this issue, design platform-specific detection, file implementation tickets.

[mcdays94]

Status: deferring this slice indefinitely (no field signal)

Picked up grilling on this 3 weeks after slice 1 shipped in v0.9.8 and 2 weeks after slice 2 in v0.9.9. Before grilling the design, walked the foundational question the issue body itself raises: "this slice may be deferred indefinitely based on user feedback after slice 1 ships."

Three classes of evidence would justify proceeding:

1. Community reports of SMART staleness despite slice 1's max-age safety net (smart.max_age_days + smart.wake_drives)
2. Observations showing the max-age force-wake fires regularly at the default 7-day cadence (suggesting drives never naturally awake during scan windows, so a passive piggyback would catch nothing anyway)
3. Complaints that the max-age force-wake itself is the problem (extra wear, noise, spin-up latency) and users would prefer an opportunistic alternative

None of the three has surfaced. Issue-tracker audit on 2026-05-10:

• 0 open issues touching SMART staleness, spin-up timing, or active piggyback from anyone other than the maintainer
• Closed Scans spin up array disks in Unraid #127 (slice 1's origin, @geransmith) was about the opposite concern (too much wake-up); slice 1's -n standby + opt-in wake toggle solved it
• Closed The history values for all drives are not being updated #162 (drive history not updating, @TheTwist76) looked initially relevant but turned out to be template drift (missing /dev//sys//var/local/emhttp bindings on an old CA template), resolved by re-pulling the current template. Orthogonal to slice 3.

Decision: parking slice 3. Slice 1's max-age fallback appears to be covering the value space adequately based on the absence of signal. Building active piggyback now would be engineering-heavy (per-platform detection rabbit hole: /var/local/emhttp parsing for Unraid, /proc/diskstats deltas for generic Linux, sysfs polling for power state) without a corresponding user-visible problem to solve.

What would reopen this:

• A bug report like "SMART data stale despite smart.max_age_days=7 and smart.wake_drives=true"
• A user reporting the max-age force-wake is itself the problem they want avoided
• Observing in UAT or any self-deployment that the max-age force-wake fires daily on a typical 7-day cadence (meaning drives never happen to be awake during the scan window, so passive piggyback would also see nothing)

Keeping this open as a tracker; not closing. Will re-grill if any of the above lands.