docs(series4): "not polling" and "unreachable" are different states

Follow-up to the reproduced wedge, and the sharpest point to come out of it --
the operator's observation, demonstrated directly.

At 13:10:44, six and a half minutes after THOR's last connection of any kind:

    THOR connections since 13:04:22 : 0
    independent POLL through the same relay, same moment : succeeds

The unit is reachable.  The link is fine.  THOR is simply not asking.

So whatever THOR's UI reports in that window is wrong.  "Connected/OK" is false
because nothing has been checked for minutes.  "Disconnected/unreachable" is also
false because the unit answers on demand.  The true state -- "I have given up
checking this unit" -- is not one THOR can display.

An operator therefore cannot separate "the unit is down" from "the poller is
asleep", and those demand completely different responses: a site visit versus a
mouse click.

This settles a question the previous commit left open.  It does not matter much
whether stopping after one retry is intentional or a defect: the reporting is
wrong either way, since both plausible displays misrepresent reality.

Sharpens design consequence 4 accordingly -- a unit's displayed state should be
one of: checks passing, checks failing (with attempt count and last error), or
not being checked (with why, and a way to resume).  Collapsing the last two into
a single indicator is the root of this failure being undiagnosable.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ru8Lg9HkkYvX9VWWo65SmL
This commit is contained in:
2026-09-25 13:11:18 -04:00
co-authored by Claude Opus 5
parent 04b1ef3e04
commit eccd28ea0d
+38 -6
View File
@@ -1811,10 +1811,38 @@ while nothing is actually watching it. The operator sees a successful check and
moves on; the background loop stays dead. That is worse than a refresh button
that plainly fails, because the failure is *silent and looks like success*.
It also explains why the field symptom is hard to characterise: the unit is
perfectly reachable the whole time. Poke it and it answers. Nothing is wrong
with the unit, the modem, or the link — THOR has simply stopped asking, and says
nothing about it.
### 🔑 "Not polling" and "unreachable" are different states — and THOR conflates them
Demonstrated directly. At **13:10:44**, six and a half minutes after THOR's last
connection of any kind:
```
THOR connections since 13:04:22 : 0
independent POLL through the same relay, same moment : succeeds, correct response
```
**The unit is reachable. The link is fine. THOR is simply not asking.**
Whatever THOR's UI reports in that window, it is wrong:
| if it shows | why it is false |
|---|---|
| connected / OK | nothing has been checked for minutes |
| disconnected / unreachable | it **is** reachable — THOR stopped trying |
The true state is *"I have given up checking this unit"*, and no display in THOR
expresses it. So an operator cannot separate **the unit is down** from **the
poller is asleep** — and those demand completely different responses: a site
visit versus a mouse click.
This also settles a question the previous section left open. It does not much
matter whether stopping after one retry is an intentional design choice or a
defect: **the reporting is wrong either way**, because both plausible displays
misrepresent reality.
It explains, too, why the field symptom resisted characterisation. The unit is
perfectly reachable throughout. Poke it and it answers. Nothing is wrong with
the unit, the modem, or the link.
### Design consequences for SFM
@@ -1826,8 +1854,12 @@ nothing about it.
3. **Surface the poll loop's own state** — last successful check, last attempt,
next scheduled attempt, consecutive failures. All four were invisible here,
and every one of them would have made this diagnosable in seconds.
4. **Distinguish "unit unreachable" from "we stopped checking."** They present
identically in THOR and have completely different causes and fixes.
4. **Distinguish "unit unreachable" from "we stopped checking."** Proven above
to be different states that THOR cannot tell apart. A unit's displayed state
should be one of: *checks passing*, *checks failing* (with the attempt count
and last error), or *not being checked* (with why, and a way to resume).
Collapsing the last two into one indicator is the root of this whole failure
being undiagnosable.
### Caveats