docs: handoff for v1.2.14 Windows pair failures (3 findings)#105
Merged
Conversation
Captures the diagnostic work from a 1.2.14 Windows install session for the next agent to act on. Three distinct failure modes, all surfacing to the user as the same "splash never advances" symptom but caused by unrelated bugs in different layers. 1. `Invalid Version: vundefined.undefined.undefined` on WebUSB pair — defensive fix in flight at keepkey/hdwallet#37 (with regression tests). Bumping the submodule pointer here is a follow-up after that PR merges. 2. Native crash on USB unplug during in-flight WebUSB write — bun process disappears with no JS error after libusb's `bad write`. Same family as the existing macOS attach-time SIGTRAP guard in engine-controller.ts:251-254. Open; suggested approach in the doc ranges from a process-supervisor band-aid to moving USB I/O into a child process. 3. Splash hangs forever when port 1646 is already bound — the FATAL exit message is in the backend log but the BrowserWindow is created before the port collision check, leaving an undecorated splash on screen. Open; fix is to move the collision probe before window creation and/or surface a "Vault is already running" UI state. Doc includes log evidence for each finding, root-cause file pointers, reproduction recipes, and an explicit "what is NOT broken" section to prevent the next agent from re-investigating the verified-intact download, the 1.2.14 @noble/hashes fix, the protobuf schema, and the frontend bundle.
BitHighlander
added a commit
that referenced
this pull request
Apr 9, 2026
Bump version to 1.2.15 and pin hdwallet submodule to master (includes keepkey/hdwallet#37 — Features version validation). Changes since v1.2.14 pre-release: - fix(win10): skip POSIX heartbeat watchdog on Windows (#107) - fix: sync file logger — crash logs now survive native exceptions (#107) - fix: boot environment dump for launch-context diagnostics (#107) - fix: JS↔native boundary logging in engine-controller (#107) - fix: port 1646 collision check before window creation (#106) - fix: USB detach race guard on WebUSB pair (#106) - fix: hdwallet Features version validation (hdwallet#37) - docs: handoff for 1.2.14 Windows pair failures (#105) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Captures the diagnostic work from a 1.2.14 Windows install session for the next agent to act on. Three distinct failure modes, all surfacing to the user as the same "splash never advances" symptom but caused by unrelated bugs in different layers.
Invalid Version: vundefined.undefined.undefinedon WebUSB pairbad write→ process gone)This PR adds only
docs/HANDOFF-1.2.14-WINDOWS-PAIR.md— no code changes. The doc is the work order for whoever picks this up next.What's in the doc
For each finding:
vault-backend.log(timestamps, line content, timing gaps that distinguish synchronous failures from real USB roundtrips)Plus:
@noble/hashesfix, the protobuf schema, and the frontend bundleWhat this PR is not
Why a doc PR
The investigation produced more context than is reasonable to keep in chat history or commit messages. A markdown file in
docs/survives, is greppable, and the next agent can land on it viaWINDOWS-filename neighbors (WINDOWS-DEV-MODE.md,WINDOWS-OOB-REGRESSION.md,WINDOWS-QUIRKS.md).Test plan
develop