keyrelay/.agents/HW_VERIFICATION.md

HW_VERIFICATION.md — the device half of this roadmap's verification

The host gate (.agents/validate.sh) proves what can be proven without a board: the pure-module suites under sanitisers, the page and tool suites, both firmware builds, repo hygiene. It deliberately contains no -t upload, no curl to a device, no network fetch — an upload in a gate is a device side effect on somebody else's schedule (AGENTS.md).

That leaves claims that only a device can answer. AGENTS.md's standard: "A feature that lives on the device is not done when the source builds — it is done when the device is running it and something observed it." This file pairs every such claim in phases 02–05 with the exact command that observes it and the observation that counts, and states the rule that keeps a unit from ever blocking on a board nobody is holding.

bash tools/hw_probe.sh (printed at the end of every gate run, exit status deliberately ignored) says what is reachable right now — serial nodes, keyrelay.local, http/https, uv/node, target-side evdev nodes — without side effects and without blocking. It informs; it never gates and never records an outcome by itself.

Baseline (measured, phase 01 task 01 gate run)

Later phases quote a delta against these numbers, never a fresh guess.

metric	value
bridge RAM	26.7 % (87 592 / 327 680 B)
bridge Flash	36.1 % (1 135 293 / 3 145 728 B)
console RAM	16.8 % (55 200 / 327 680 B)
console Flash	33.6 % (1 056 081 / 3 145 728 B)
host checks	3406 (3162 C++ + 160 relayctl + 84 page), green in the normal and the SANITIZE=1 run
served page	48 598 bytes — the raw-string length the gate prints every run; a reflashed device must serve exactly this many

Phase 02 additionally quotes the heap cost of one and two live TLS sessions as a delta against the bridge RAM/heap line above.

Claims that need hardware

Outcome vocabulary, written into the row in the phase's commit by whoever ran the command: ok · skipped (no device) · failed: <what>. Blank = not run yet. A row nobody ran is recorded skipped (no device) at phase close — an unobserved claim is never back-filled with a guess (ASSUMPTION: unattended runs may have a board attached that nobody is watching, and a second machine for watch_target.py is rarer than either).

Every phase that touches the keystroke path (02–05 regression baseline)

claim	command	expected observation	outcome
keystrokes reach the target	python3 tools/watch_target.py --seconds 60 on the target, driven from the page or tools/relayctl.py	one press and release per key with timestamps; still held absent from the summary
a chord is the keys its label claims	python3 tools/relayctl.py --host keyrelay.local chord 04 2b while watch_target.py runs	LAlt press then Tab press — and not LCtrl. The watcher is the only thing that says what the target received (README: Alt+Tab was Ctrl+Alt+A on the wire once)
served page == built page	curl -s http://keyrelay.local/ | wc -c (after phase 02 lands: curl -sk https://keyrelay.local/ | wc -c)	byte-equal to the page bytes: line the gate prints. A mismatch means the page in flash is stale — reflash and reload any open tab	ok — measured 2026-11-09: curl -s http://keyrelay.local/ | wc -c = 48598 = gate's count (board on the LAN, pre-TLS, serving over http as expected). Re-run by the phase 01 final pass, one capped attempt each: 200 / 48 598 bytes, 404 on /nope, 401 on /status without the token, zero src=/href= in the served bytes. The first cold probe returned nothing (http_code=000, glibc does not cache mDNS) and the retry worked — that retry is the documented behaviour, not a second attempt at the check
silence disarms	arm, kill the controller process without a clean close (or close the tab), wait kNoClientTimeoutMs (8 s), python3 tools/relayctl.py --host keyrelay.local status	armed: 0, and watch_target.py shows releases for anything held. Test the timer, not the socket close (README bug 10)
nothing outlives the link	hold a key and a mouse button, then drop the link	every key up, every button up; mouse summary shows no still held

Phase 02 — HTTPS + wss://

claim	command	expected observation	outcome
TLS handshake completes	curl -sk https://keyrelay.local/status or openssl s_client -connect keyrelay.local:443 </dev/null	200 + status JSON / a session whose only verify failure is self-signed. HTTP 000 / connection refused = listener not up
fingerprint printed once, on serial	serial console boot log after nvs erase; then python3 tools/console.py cert (opens the port — one attempt, capped)	SHA-256 fingerprint appears exactly once at first boot, on demand afterwards; never the key; survives reflashing (NVS)
pinned fingerprint == handshake cert	openssl s_client -connect keyrelay.local:443 </dev/null 2>/dev/null | openssl x509 -noout -fingerprint -sha256	same hex as the serial console printed; mismatch = two identities, investigate before pinning
:80 is redirect-only	curl -s -o /dev/null -w '%{http_code} %{redirect_url}' http://keyrelay.local/	3xx to https://, and no page bytes on plaintext
plaintext /ws refused, not downgraded	a ws:// upgrade attempt on :80 (e.g. curl -i -N with upgrade headers, or relayctl.py pointed at plaintext)	refused loudly (per README error style), never a silent plaintext session
TLS session heap cost	build RAM delta from the gate output + live free-heap readout the phase's status/serial path exposes, at 0 / 1 / 2 live sessions	quoted as a delta against the baseline table above; two sessions must fit without allocation failure
-D KR_TLS=0 rollback behaves like today	build the rollback env, flash once, curl -s http://keyrelay.local/ | wc -c + page connects over ws://	page and ws:// work exactly as pre-phase-02; README documents the rollback

Phase 03 — session takeover

claim	command	expected observation	outcome
takeover releases the incumbent's held keys	two controllers on one board: incumbent holds a key, newcomer takes over (relayctl.py --take-over), all while watch_target.py runs on the target	watch_target.py shows the key up before the new session's first key-down — the ordering is the whole claim
the board comes back disarmed	python3 tools/relayctl.py --host keyrelay.local status immediately after the handover	armed: 0 across the handover; the newcomer must arm again on purpose; nothing in the handover path arms
a third controller is still refused	a third /ws upgrade while two sessions exist	E3 — takeover consumes the one spare slot, it does not open the door

Phase 04 — responsive page

claim	command	expected observation	outcome
page still byte-exact after the restructure	the generic curl … | wc -c row above	equals the gate's new page bytes: count (the count moves when the page does — that is fine; equality with the gate is the check)
one column on a phone, ARM thumb-reachable	open https://keyrelay.local/ on a phone at ~360 px	single column, no horizontal scroll, sticky ARM bar on screen, log collapsed and not pushing ARM off screen

Phase 05 — soft keyboard and touch pad

claim	command	expected observation	outcome
arm on a phone raises the soft keyboard, characters land	phone on the board's AP/network, tap ARM, type a word; watch_target.py on the target	phone keyboard appears; the watcher's typed: line reproduces exactly what was typed, one P=0: character per frame
a latched modifier chords correctly	latch Ctrl on the row, tap c; watch on the target	LCtrl press + C press — Ctrl+C on the wire, latch visibly cleared after
pad moves the pointer; lift releases everything	press-and-hold the pad, move, lift; hold a button meanwhile, then drop the link	movement dx … dy … lines that stop at lift; still held absent from the mouse summary; no button stuck

The blocking rule

A unit running any of the rows above:

1. Look first, side-effect-free. bash tools/hw_probe.sh (always exits 0, every probe capped, no serial port opened — opening /dev/ttyACM* toggles DTR/RTS and resets the board). It tells you whether an attempt is plausible.
2. One attempt, capped. Each device step runs at most once, wrapped in timeout (or the tool's own -m). No polling a port, no retry loops, no re-powering, no re-flashing "to see if it works". A timeout is an outcome (failed: timeout … or skipped (no device)), not a cue to try again.
3. Record what was observed. The outcome — ok, skipped (no device), failed: … — plus the exact command written goes into the row above, in the phase's commit. Never write ok for a command that did not run; the unattended-run contract is that the human picks these rows up later.
4. Never strand the board. tools/to_bootloader.py drops the board into ROM download mode deliberately, and a power cycle is the only way back. If a run leaves the board in download mode, its report says so explicitly — nobody may be there to notice.
5. Never block the gate. None of this is inside .agents/validate.sh. The gate stays device-free and network-free; the probe line at its end is context whose exit status is deliberately discarded.