fix(scripts): reset-aware handshake refuses a null reset value; document additive timeouts (#36 review)

A null resetValue encoded to null, which wrote an empty string and then handed the
waiter a null target (= any change), fast-pathing on the stale cache and reinstating
the race the overload exists to close. The context parameter is now non-nullable and
the accessor throws ArgumentException before any write. Also: additive-timeout note on
all surfaces, batch-failure message no longer names the bool overload, and the
error-message/batch-failure branches are pinned.

Claude-Session: https://claude.ai/code/session_01XPsuy2ZZ5Gbyfpt8PrK5BV
This commit is contained in:
Joseph Doherty
2026-09-10 15:35:50 -04:00
parent 637da6c020
commit 17d5d3e639
8 changed files with 138 additions and 12 deletions
@@ -126,6 +126,11 @@ if (!hs.Matched)
arrives after this run's reset echo can still satisfy the response wait. A level-triggered flag
protocol cannot distinguish that case; it needs a sequence/handle attribute on the device side.
**The two waits are additive.** A call can run for `resetTimeout` + `timeout` plus Ask slack, so a
script using the overload must set `ExecutionTimeoutSeconds` above that sum. A script deadline hit
part-way through either leg propagates as cancellation (§4.3) — the script sees the cancellation,
not a `HandshakeResult` naming the phase it died in.
## 6. Mirrors and analysis surfaces
- `ScriptCompileSurface` (ScriptAnalysis) — compile-only mirror of the new overload