feat: LED signals an unacknowledged fault instead of being permanently on

[varffs]

What

The button LED (GPIO 17) was switched on at boot and never off. It carried no information — on when healthy, on when the external probe was dead, on at 3am. The polytunnel box is visible from the house, so it was light pollution with no payload.

This redefines it as "there is a fault and you have not looked at it yet."

Three conditions must hold simultaneously for the LED to be lit:

1. at least one fault is active, and
2. at least one active fault is not in the set last acknowledged, and
3. it is not the quiet period (sunset + 30 min → sunrise − 30 min)

No state exists in which the LED is steadily on. Lit means a 750 ms pulse inside a 3 s cycle.

How it behaves

• Faults: int (internal AHT20 read failed), psh (3 consecutive push failures = 15 min of sustained failure), clk (booted with an insane clock — sticky, so it can still report once NTP lands), ext (external DS18B20 not ok). "unknown" is the boot value and is deliberately not a fault.
• Acknowledgement is physical: cycling the display to DIAG requires standing at the device, so looking is acknowledging. The acknowledgement covers only faults still live, so a fault that clears and returns is new again.
• Night suppression is computed locally from the site coordinates via suncalc — no network call. At 50.77°N the LED is permitted roughly 04:30–21:50 local at midsummer and 07:40–16:35 at midwinter. The long winter blackout is intended.
• DIAG screen: line 0 still shows ext: <status>; line 1 now shows int / psh / clk flags when any are live, displacing the diagnose() text until they clear.
• Restart re-arms, because seenFaultKey is not persisted. With the external probe dead that means the LED pulses after a restart until someone visits — deliberate: an unexplained restart is worth knowing about.
• LED_IGNORE_QUIET=true bypasses night suppression for development, otherwise evening work on the laptop shows a permanently dark LED and reads as broken.

Verification

103 tests passing. app.js is outside the test import graph, so the wiring was verified by running it: measured 751 ms on / 2255 ms off with a fault forced, silent when healthy, pulsing stopped the instant DIAG was reached, and a real-time run at 01:23 BST stayed dark with a fault active — the night gate works against the actual clock.

Notes for review

• suncalc 2.0.1 is ESM with named exports only — no default export. The import form is import { getTimes } from "suncalc". Single file, no runtime deps, no native bindings, no postinstall, so armv6 is unaffected. The device cannot run the suite (Node 16.14, node --test needs 16.17+), so a load-time import error would only surface on deploy.
• The acknowledgement rule is two interacting halves — containment in selectArmed, intersection in the reducer's post-pass — and each is correct only because of the other. Both defects found in this area were caught by review rather than by test; a property test would serve better than more examples. Worth a follow-up ticket.
• app.js has no test coverage and gained three listener registrations plus a shutdown ordering requirement here. Also worth a ticket.
• Not done, deliberately: explicit serializableCheck/immutableCheck: false in configureStore, which would retire the device's dependence on NODE_ENV=production living only in pm2's saved dump. Left as an owner decision because it also removes the dev-mode safety net.

Spec: docs/superpowers/specs/2026-07-27-led-fault-signal-design.md
Plan: docs/superpowers/plans/2026-07-27-led-fault-signal.md

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR changes the GPIO 17 button LED from a “power on forever” indicator into a meaningful fault signal: it now pulses only when there is at least one active, unacknowledged fault, and it is suppressed during a computed night “quiet period” (sunset+30min → sunrise−30min).

Changes:

• Add a pure fault-derivation module (src/faults.js) with a stable ordered fault key and “armed” (unacknowledged) detection.
• Implement acknowledgement semantics in the reducer (entering DIAG records the current fault set; acknowledgements shrink to live faults; clock-insanity is sticky until DIAG is read and exited).
• Add quiet-period calculation via suncalc (src/solar.js) and wire a listener-driven LED blink loop (src/led.js) into app.js, plus config for site/timing and dev override.

Reviewed changes

Copilot reviewed 20 out of 21 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/store.test.js	Expands reducer tests for new sensor/LED state, acknowledgement narrowing, and clock fault behavior
src/store.js	Adds internal/push/LED state, sticky clock flag logic, DIAG acknowledgement capture, and post-pass acknowledgement narrowing
src/solar.test.js	Tests quiet-period logic across seasons, boundaries, and “bad clock” handling
src/solar.js	Implements isQuietPeriod() based on SunCalc sunset/sunrise windows with a margin
src/sensors.test.js	Adds coverage ensuring internal sensor status is dispatched on success/failure
src/sensors.js	Dispatches sensors/internal/status as "ok"/"error" from pollInternal
src/render.test.js	Adds DIAG rendering coverage for fault flags vs external diagnostic text
src/render.js	Shows non-ext fault flags on DIAG line 1 when present
src/led.test.js	Adds listener-middleware tests validating pulse behavior, quiet suppression, and disarm behavior
src/led.js	Implements the listener-driven blink loop gated by “armed” and injected quiet-check
src/faults.test.js	Adds unit tests for fault detection, key ordering, and armed semantics
src/faults.js	New pure selectors: selectFaults, selectFaultKey, selectArmed (+ constants)
src/config.test.js	Verifies new site/timing config and LED_IGNORE_QUIET override behavior
src/config.js	Adds site coords, quiet margin, blink timings, and dev override flag
package.json	Bumps version to 2.1.0 and adds suncalc dependency
package-lock.json	Locks suncalc@2.0.1
docs/superpowers/specs/2026-07-27-led-fault-signal-design.md	Adds the detailed design spec for the new LED semantics and architecture
docs/superpowers/plans/2026-07-27-led-fault-signal.md	Adds the implementation plan and test expectations
CHANGELOG.md	Adds 2.1.0 release notes describing the LED behavior changes
app.js	Wires in blink + GPIO sync listeners, push outcome reporting, boot LED off, and shutdown listener cancellation
.env.example	Documents LED_IGNORE_QUIET dev override

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.