[malpern]

Summary

With all-keyboards Caps Lock (#1339), a newly plugged-in keyboard was mapped by the worker's 2 s poll. Now an IOKit notification brings that check forward.

• SessionCapsKeyboardArrivalMonitor listens for IOHIDEventService first-match notifications. Services already present at startup are ignored. It classifies each new service with the lease's own serviceEmitsKeyboardUsages, on a background queue rather than the event tap's run loop, and fails open when a service's capability can't be read yet.
• SessionCapsCheckSchedule decides when the fleet reconcile runs:
  • No check runs in the 0.25 s after the first arrival since the last check. A held key on the new keyboard isn't known until its first report has been processed.
  • Then one early check runs. If hidutil hasn't listed the keyboard yet (matched by registry ID, or another interface at the same LocationID), up to five more follow, each 0.25 s after the previous one finishes.
  • All early checks share a budget of 12 per 10 s, so a flapping device falls back to the 2 s backstop. That backstop is measured between check starts and delayed by one pause at most.
  • A failed check hands over to the backstop. Lease contention keeps the fast checks through two busy results.
• Logging: [SessionCaps] Keyboard covered for each newly covered keyboard, and [SessionCaps] Keyboard arrival mapped in N ms, timed from that keyboard's own arrival. A keyboard covered for another reason isn't timed. A sibling interface keeps the first arrival time; a replug at the same LocationID resets it.
• Docs: the hot-plug section of docs/architecture/all-keyboards-caps.md is rewritten. guides/driverless-caps-lock.md describes plugging in a keyboard.

Eligibility, exclusions, the all-keys-up gate and the existing-remap policy are unchanged. The monitor only schedules checks.

Testing

On the MacBook Air (Xcode 27.0):

• ./Scripts/run-tests-safe.sh: 5,860 tests passed.
• SessionCapsCheckScheduleTests (31 tests) cover:
  • the schedule;
  • the off-main classify and on-main delivery path, including a result that lands after stop();
  • a 20 s tick-loop simulation of a device re-registering every 0.2 s;
  • replug, sibling-interface and attribution timing;
  • backoff pruning;
  • a unit check that a high-bit LocationID reads the same from IOKit and hidutil.
• Opt-in live tests, run with KEYPATH_LIVE_CAPS_FLEET=1, passed on the Air: the lease predicate recognises an attached keyboard, and IOKit and hidutil agree on LocationIDs.
• Two tests were checked by mutation and fail against the bugs they guard: reporting the startup inventory as arrivals, and timing the pause from the latest arrival.
• ./Scripts/review-gate.sh: PASS, after nine failing rounds whose findings are all addressed in this branch.

Not verified

• No physical replug test yet. The arrival mapped in N ms time hasn't been measured. The Air is in single-keyboard mode; switch to all keyboards in Settings, then plug in an external keyboard and read the log.
• Whether 0.25 s is long enough for macOS to report a key held on a new keyboard is unmeasured. A second keyboard arriving inside the first one's pause is checked less than 0.25 s after its own arrival. The ESP32 fixture with a key held would settle both, once the mini is back.
• CI and the lab are unavailable while the mini is offline.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-25T18:22:01.716939Z	e87589d	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Review of PR 1343 (IOKit arrival-triggered Caps fleet check)

I found no blocking correctness issues in the supplied diff. The diff was truncated at 60 KB, so I did not see the tail of docs/architecture/all-keyboards-caps.md or the guide change. I also couldn't build or run the tests here.

What I checked:

• The schedule logic holds up: the settling pause, the shared early-check budget, the busy/failed hand-over to the backstop, and the arrival-generation handling all behave correctly in the cases I traced.
• The monitor handles teardown correctly. The port and source are removed in stop(), and the self.port != nil check drops classifications that finish after stop().

Minor, non-blocking:

1. Wall-clock time: SessionCapsCheckSchedule takes Date and compares it against lastStart, lastEnd, earlyStarts and settlingSince. A backward clock step (NTP, manual change) makes timeIntervalSince negative. That can leave settlingSince or earlyStarts entries looking fresh, which would delay checks past the settling pause or exhaust the early budget until the clock catches up. The 2 s backstop is also blocked while settlingSince is set. A monotonic source (ContinuousClock or ProcessInfo.systemUptime) would be safer. The worker already uses Date elsewhere, so this is optional.
2. Test timing: testMonitorStartsWithoutReportingKeyboardsAlreadyConnected and testAClassificationFinishingAfterStopIsDropped rely on real RunLoop.main.run(until:) sleeps (0.5 s and 0.3 s). They can't fail spuriously, but a late delivery could pass unnoticed on a slow host.
3. Unreadable registry IDs: drain maps an unreadable registry ID to 0. classify handles this by returning nil, so these arrivals trigger a check but are never tracked. That matches the documented fail-open intent.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e87589d303

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Review of PR 1343 (the supplied diff was truncated at 60 KB, so the rest of the docs and guide changes were not reviewed).

I found no blocking correctness issues in the reviewed part (the arrival monitor, the check schedule, the worker changes and the tests).

• Schedule logic: The settling pause, the shared early-check budget (12 per 10 s), the generation counter for arrivals that land mid-check, and the busy/failed hand-over to the backstop are consistent with each other. The tests cover them, including a clock step back and a device that re-registers faster than the pause.
• Monitor lifecycle: Classification runs off the main thread, and a result that lands after stop() is dropped. finish() stops the monitor.
• Nit: startCapsArrivalMonitor() assigns capsArrivalMonitor unconditionally. This is fine if the fleet-enable path runs once, which I could not confirm from the diff. If it can run again, stop the old monitor before replacing it, or guard on capsArrivalMonitor == nil.
• Test gap: The worker-side wiring in checkCapsFleetIfNeeded is not covered by a test. That wiring covers the resolved computation from the captured hidutil listing, the departed backoff cleanup, and the checkBusy/checkFailed routing. Only the static helpers are tested. This is acceptable given the live-hardware dependency, and the physical replug measurement is still marked as pending in the docs.

[claude]

Review (diff truncated at 60k bytes; docs/guides tail not reviewed)

Found two things worth addressing:

1. checkFinished can clear fast checks after a failed/busy-path mismatch — in SessionRuntimeWorker.checkCapsFleetIfNeeded, the .failure branch for busy calls checkBusy() but never updates capsTimedArrivals for coverage or resolves anything; that's fine. However lastCapsCheckEnd is set in the completion handler before the guard digest == nil || digest == admittedDigest / capsOwner == owner checks pass only for the owner case. If capsOwner != owner the early return skips capsCheckInFlight = false, which is pre-existing, but the new schedule state (checkStarted already called) is left without a matching checkFinished/checkFailed. Low risk, but generationAtStart stays stale.

2. Settling pause can starve the backstop — isDue returns false for the entire afterArrival (0.25 s) window from the first arrival, and settlingSince is only cleared in checkStarted. Since the window is anchored at the first arrival and not extended, starvation is bounded (good), but a device re-registering faster than 0.25 s while earlyBudget is exhausted still gets one check per 0.25 s window only when wantsEarly; otherwise it falls to the backstop and is fine. Test testADeviceReRegisteringFasterThanThePauseStillGetsChecked covers this. No action needed.

3. Test coverage: SessionCapsKeyboardArrivalMonitor.start() failure path and stop() during an in-flight IOKit callback are only covered on hosts with IOKit (tests skip otherwise); CI on non-hardware runners may exercise little of the monitor.

No blocking correctness issues found in the visible portion. 🤖 Generated with Claude Code