🐛 (device-management-kit): Map the 0x6901 status word to a typed error

[ritiklakhwani]

Fixes #1773.

The bug
While the device's own interface is in the foreground, BOLOS answers every APDU with 0x6901, under the 0xb0 CLA as much as 0xe0. That code is not in GLOBAL_ERRORS, which maps only 5515 / 5501 / 5502 / 5223 / 6e00 / 6d00, so it falls through to UnknownDeviceExchangeError.

The consequence is worse than an unhelpful message. OpenAppDeviceAction begins at GetDeviceStatus, which goes through GetAppAndVersionCommand. That result is an error, the machine transitions straight to Error, and 0xe0d8 is never sent. The device displays no prompt, so from the user's point of view tapping connect does nothing at all.

The locked-device path is the useful comparison. 0x5515 is mapped, so WaitForAppAndVersionDeviceAction recognises it, requests UserInteractionRequired.UnlockDevice, and keeps polling until unlockTimeout. Same shape of problem, graceful recovery. The only difference is whether the status word is in the table.

The change
Adds 6901 to GlobalCommandErrorStatusCode and to GLOBAL_ERRORS, plus a row in the existing table-driven test.

One naming question for you
The natural tag here is DeviceBusyError, but that name is already taken by a class in api/Error.ts. It appears to be unused — I could not find anywhere it is constructed — but two error types sharing a _tag would break discrimination for consumers matching on it.

So I used DeviceNotReadyError and put the precision in the message. Happy to switch to DeviceBusyError if you would rather reuse it, or to any name you prefer.

Deliberately not addressed
The issue raises two further points that read as design decisions rather than missing entries, so I have left them alone:

DeviceSession.sendApdu classifies anything that is not a locked-device response as CONNECTED, so a session refusing every command still reports deviceStatus: CONNECTED with currentApp: undefined.
The status word survives only on originalError.errorCode and is not part of the public typed surface.
Happy to follow up on either, together or separately, if you would like them handled.

Verification
pnpm test # device-management-kit: 1056 passed, 109 files
pnpm typecheck # 77 of 77 tasks successful
pnpm lint # 0 errors; the 53 warnings are pre-existing and in other files
prettier --check # both changed files conform

Changeset included, patch bump.

Context
Found while building a pre-signing risk check for AI agents that routes high-risk verdicts to a Ledger for physical confirmation: https://github.com/ritiklakhwani/preflight

We hit the same class of problem in our own code: unmapped device states turning into unreadable errors for whoever is standing at the device. A locked Ledger surfaced to our users as truncated JSON, and a disconnect as DeviceDisconnectedBeforeSendingApdu, until we built a translation layer. This is that lesson applied one level down.

[vercel]

@ritiklakhwani is attempting to deploy a commit to the LedgerHQ Team on Vercel.

A member of the Team first needs to authorize it.

[Copilot]

🟢 Approval recommended

The mapping, test coverage, and changeset are included with no unresolved review issues.

Pull request overview

Maps APDU status 0x6901 to a typed DeviceNotReadyError.

Changes:

• Adds the status code and global error mapping.
• Adds table-driven test coverage.
• Includes a patch changeset.

File summaries

File	Summary
packages/device-management-kit/src/api/command/utils/GlobalCommandError.ts	Registers the 0x6901 error mapping.
packages/device-management-kit/src/api/command/utils/GlobalCommandError.test.ts	Tests the new typed error.
.changeset/wild-donkeys-report.md	Documents the patch release.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.