Upstream: migrate Kanata to the current VirtualHIDDevice protocol

[malpern]

Direction

Treat this as an upstream-first Kanata compatibility project, independent of KeyPath integration.

The immediate goal is to make the latest upstream Kanata compatible with the current Karabiner-DriverKit-VirtualHIDDevice protocol, validate the result as a standalone Kanata change, submit it upstream, and get it merged. KeyPath should consume the upstream result afterward in a separate integration step.

Do not update the KeyPath submodule, bundled driver package, release scripts, installer, or macOS 27 lane as part of the upstream PR.

Context

Karabiner-DriverKit-VirtualHIDDevice v8.0.0 uses client protocol 7. The Kanata driverkit client currently targets the older protocol-5 API and local-datagram transport.

Breaking changes since the currently supported driver include:

• v7 changed IPC from pqrs::local_datagram to pqrs::unix_domain_stream and moved the client protocol from 5 to 6.
• v8 removed virtual_hid_device_service::request::get_status, changed subsequent request enum values, removed virtual_hid_device_service/utility.hpp, and moved the protocol from 6 to 7.
• Clients using the embedded C++ headers must be rebuilt and adapted to the new API.

KeyPath also carries Kanata-side work that must not be lost when designing the upstream change:

• fast reconnect/reset behavior from malpern/kanata PR refactor(wizard): consolidate service pages (Communication + Kanata Service) #26, commit 7890acf
• report-set convergence and telemetry from PR refactor(managers): split KanataManager into focused extensions (no behavior change) #28, commit ea7ec53

Verify authorship and current upstream provenance before deciding whether each behavior should be ported, redesigned, or omitted.

Phase 1: upstream Kanata implementation

Work from the latest jtroo/kanata main branch in a dedicated Kanata checkout and branch.

1. Reproduce the current incompatibility against VirtualHIDDevice v8.
2. Update the Kanata karabiner-driverkit client and vendored headers/source to the selected current protocol.
3. Replace removed status APIs with the supported client signals:
   • driver_activated
   • virtual_hid_keyboard_ready
   • virtual_hid_pointing_ready
4. Port the reconnect, report-reset, convergence, and stuck-key protections where they remain semantically necessary.
5. Add focused automated coverage around protocol framing/state, readiness transitions, reconnect behavior, report convergence, and shutdown cleanup.
6. Test standalone Kanata with the matching current VirtualHID daemon on supported macOS versions available outside KeyPath.
7. Keep the upstream diff focused and free of KeyPath-specific paths, packaging, naming, or assumptions.
8. Open a PR against jtroo/kanata, address upstream review and CI, and continue until it is merged.

Upstream acceptance criteria

• Latest upstream Kanata builds against and communicates with the selected current VirtualHIDDevice release.
• Client and daemon use the same protocol version.
• No references remain to removed v8 APIs.
• Keyboard output, readiness, reconnect, shutdown, and stuck-key recovery are validated.
• The implementation is acceptable upstream and the Kanata PR is merged.

Phase 2: KeyPath integration

Begin only after the upstream Kanata work is merged.

Create a separate KeyPath issue or focused follow-up PR to:

• update the KeyPath Kanata fork from the merged upstream commit
• reconcile any remaining KeyPath-only patches without duplicating upstream behavior
• update the bundled VirtualHID package and release tooling
• rebuild the Kanata engine and host bridge
• run signed/notarized install and upgrade verification
• hand the resulting build to the separate macOS 27 validation lane

Non-goals for the upstream PR

• KeyPath installer or UI changes
• KeyPath release packaging
• KeyPath submodule updates
• broad Kanata macOS architecture cleanup
• claiming macOS 27 support without that lane completing its own validation

Completion rule

This ticket is complete when the standalone Kanata protocol migration has been merged upstream and a clearly scoped KeyPath integration follow-up exists. KeyPath adoption is downstream work, not part of the upstream PR.

[malpern]

Backlog reassessment after #988 (2026-07-12):

• Confirmed upstream latest is still v8.0.0 (ba649ef9, published 2026-07-03), with protocol 7 and the documented stream/get_status/utility.hpp breaks.
• Confirmed current bundled fork c50826f vendors protocol 5/local_datagram, so this is still actionable and is not a package-only bump.
• Verified provenance before judging overlap: the fast reconnect/reset work is KeyPath-authored in malpern/kanata PR refactor(wizard): consolidate service pages (Communication + Kanata Service) #26 (7890acf), and report-set convergence/telemetry is KeyPath-authored in PR refactor(managers): split KanataManager into focused extensions (no behavior change) #28 (ea7ec53). Those changes require semantic porting onto the v8 client, not deletion as presumed upstream duplication.
• This issue’s acceptance criteria require macOS 27 smoke validation. The current backlog lane is explicitly isolated from Regression-test permissions, daemon, and TCC behavior on macOS 27 betas #919/macOS 27 testing, so it cannot complete Upstream: migrate Kanata to the current VirtualHIDDevice protocol #982 end-to-end without crossing the lane boundary. Deferring implementation until the protocol branch can hand its rebuilt client/package to that validation lane; no code was changed here.

[malpern]

Upstream-first implementation started (2026-07-12):

• posted the two-PR migration plan on Bug: kanata not working since updating karabiner-elements to 16.1.0 jtroo/kanata#2105
• cloned current psych3r/driverkit upstream main at ff62645 into a standalone checkout
• opened draft Update VirtualHIDDevice client to v8 psych3r/driverkit#20 from malpern:codex/virtualhid-v8
• v8/protocol-7 crate builds and packages successfully under stable Xcode 26.6
• runtime installation/testing remains intentionally outstanding for an isolated Mac so this work does not mutate the shared KeyPath/macOS validation machine
• no KeyPath submodule, packaging, installer, or release code has changed

Next gates: maintainer direction on the compatibility cut/version, isolated v8 runtime matrix, driverkit merge/release, then the separate current-upstream Kanata dependency/docs PR.