Swift rewrite of the dictation client (hark serve / hark agent)

[STRML]

Summary

Implements the native Swift client that replaces Hammerspoon (supersedes #10 design and #11 implementation plan). A single hark binary with two roles:

• hark serve — HTTP server on 127.0.0.1:8911 (/health, /dictate) with key auth, wildcard-bind guard, WAV validation, and whisper forwarding.
• hark agent — hold-to-talk recorder + hotkey + DictateClient for the native app.

Packaging under swift/Packaging/ (build-app.sh produces a signed Hark.app).

Test Plan

Full SwiftPM suite is green — 48/48 tests (Config, Sanitize, WAV, Server, Integration, E2E, DictateClient, KeyFile). Two fixes landed during bring-up:

• DictateClient: construct URLSession with delegate: self. A bare URLSession(configuration:) never delivers delegate callbacks, which hung the synchronous dictate() path on its semaphore forever.
• IntegrationTests: retain the HarkServer strongly (released in tearDown) so it isn't deallocated mid-test — its connection handler holds weak self.

Also verified end-to-end: release build, ad-hoc codesign, and GET /health → {"status":"ok"} HTTP 200.

[drycode]

Heads up: I duplicated a chunk of this in #13/#14 before spotting this PR — I checked open issues and not open PRs, so I read #2's "Open questions" as still live when #10/#11 had already settled them. My fault, and #13/#14 will be closed as superseded by this one.

That does mean the agent side got run on real hardware — two Macs, both now dictating on it, Hammerspoon uninstalled and its grants revoked. Everything below is from that bring-up rather than from review, and two of them are live in this PR. Sharing so you don't have to pay for them twice.

The paste is a zero-duration keystroke

AgentController.swift:167-171 posts key-down and key-up back to back:

down?.flags = .maskCommand
down?.post(tap: .cghidEventTap)
up?.flags = .maskCommand
up?.post(tap: .cghidEventTap)

Some apps silently drop that. The implementation being replaced held the key for 200 ms — from Hammerspoon's eventtap.lua:

local keyDelay = 200000
module.event.newKeyEvent(modifiers, character, true):post(targetApp)
timer.usleep(keyDelay)

Same tap, same flags; the gap is the only difference. I used asyncAfter(deadline: .now() + 0.2) so the run loop isn't stalled.

Worth saying that this was not what broke my first bring-up — an untrusted process was — but it is a real divergence from the known-good implementation.

AXIsProcessTrusted() needs to be re-checked at paste time, and recorded

Everything up to the paste succeeds and logs happily whether or not the keystroke is ever delivered, so an untrusted process is indistinguishable from a dropped event. Checking at paste time and, on failure, telling the user the transcript is on the clipboard turned a three-round-trip debug into a one-liner.

The bigger trap is on the diagnostic side: do not determine Accessibility by querying TCC.db. An ad-hoc signature's designated requirement is a bare hash:

designated => cdhash H"6836bec46e8c7d394cf1ba94421ff18a31674867"

so every rebuild is a new identity — but the old row survives with auth_value=2 and System Settings keeps drawing a switched-ON toggle for a binary nothing trusts. My doctor printed PASS Accessibility is granted while the agent was alerting on screen that it couldn't paste. Three sources agreeing with each other and disagreeing with reality.

The fix is the rule your mic-status file already follows for the same underlying reason: only the process can answer for the process. The agent writes its own AXIsProcessTrusted() result to a status file and the shell reads that.

Ad-hoc signing costs a re-grant on every rebuild

Follows from the same cdhash point, and it bites during development rather than in CI. Worth having the installer record the installed cdhash and, when it changes, tccutil reset Accessibility <bundle-id> — otherwise the user goes to grant the permission, finds it already granted, and goes looking elsewhere.

Goes away entirely with a Developer ID signature, since the requirement becomes the certificate. That's in progress on our side.

Confirming your entitlement is load-bearing

Packaging/entitlements.plist has com.apple.security.device.audio-input — correct, and worth stating why so nobody "cleans it up". Under the hardened runtime, without it TCC does not deny after prompting, it refuses to prompt:

Prompting policy for hardened runtime; service: kTCCServiceMicrophone requires
entitlement com.apple.security.device.audio-input but it is missing
Policy disallows prompt for ...; access to kTCCServiceMicrophone denied

The app then never appears in the Microphone pane at all, because that pane lists only apps that have successfully requested, and the code sees an instant .denied. Nothing but the unified log names the cause. I lost an hour to exactly this.

One for the migration path

tccutil reset resolves the bundle id through Launch Services, so once you delete the .app you can no longer revoke its grants — it fails -10814 and the grants stay live while the uninstall reports success. Revoking Hammerspoon's Accessibility and Microphone is arguably the whole point of #2, so the order has to be quit → revoke → uninstall.

---

Happy to open a PR against this branch with the agent-side fixes plus the installer/doctor wiring and the Lua deletion, if that's useful — or leave it to you if you'd rather keep the tree yours. Either way the details are in #13/#14's commits and comments.

[drycode]

Ran this on hardware — Studio, real dictation, against the existing Python server. It works now, and the integration commits are on dy/swift-rewrite-integration (branched off this PR's head) if you want to cherry-pick rather than take them wholesale.

Four defects, none visible to the 48 tests. Sharing the evidence rather than just the diffs.

The hotkey misses almost every release — the Phase 0 spike, answered

Hotkey.swift reconstructs the chord from keycode + modifier flags, and applies that test to both edges. The flags describe the instant the event was generated, and releasing Ctrl+Alt+Space almost always lifts a modifier at or before the space bar — so the space key-UP arrives with the modifier bits already clear and isChord is false.

Measured with a bare session tap over 45 s of ordinary use:

DOWN events: 303      (auto-repeat while held)
UP events:     1
tap disabled:  0      (so it is not the timeout path)

One release out of dozens. In the agent that leaves a capture that never ends, and since beginCapture() guards on state == .idle, every later press is ignored — presenting as "the hotkey stopped working" rather than as a missed key-up.

Loosening the key-up test would mean tracking "a capture is open, end it on any space key-up", which re-implements something the OS already does. Switched to Carbon RegisterEventHotKey: pressed and released arrive as distinct events, the release is not conditional on modifier state, it consumes the chord so it does not also reach the focused app, and it needs no permission of its own — which answers the Phase 0 question directly: no Input Monitoring grant is needed. Accessibility is still required for the ⌘V, so it is one grant either way.

Recorder accumulates across captures

samples and peak are instance properties on a long-lived Recorder, and neither start() nor stop() clears them. Capture 2 transcribes 1+2, capture 3 transcribes 1+2+3, and the WAV grows without bound. Presents as the transcript repeating what you said last time. Reset at the top of start().

There is no presentation layer

private func alert(_ message: String) {
    log.info(message)
    NSWorkspace.shared.notificationCenter.post(name: .init("HarkAlert"), object: message)
}                                    // nothing anywhere observes "HarkAlert"

private func brief(_ message: String) { _ = message }

So the whole diagnostic surface — 401, 415, 400, 503, transport failure, "heard nothing", "paste withheld (focus moved)" — is discarded, and the menu bar title is the only feedback of any kind. Added an Overlay (non-activating floating panel, so it never pulls focus from what you are dictating into) and wired all three paths to it, keeping the menu bar item.

status.json reports a constant

writeHeartbeat passes a hardcoded hotkey: "registered" regardless of whether anything is bound — which is why the dead tap above looked healthy from the outside. Now reflects Hotkey.isRegistered.

Plus, from the previous comment

The client addressing gap turned out to be worse than a two-machine issue: my single-machine Studio binds 100.64.66.46, so 127.0.0.1:8911 refuses there too. The hardcoded loopback could not reach any deployment I have. Added ClientConfig (~/.config/hark/client.json) enforcing the transport policy your design already specifies — plain HTTP to loopback always, to a numeric IP only with an explicit allowPlaintext, to a hostname never. Absent config falls back to the current behaviour.

Also the 200 ms ⌘V hold, AXIsProcessTrusted re-checked at paste time, requestAccess waiting for its answer instead of discarding it, and a trailing space so consecutive dictations do not run together.

---

The thing I would take from all of this: every one of these passed both test suites. Yours (48) and mine (138) are green against code with all of them present, because they test what the code says and these are failures of what it reaches. The hardware spike your design asks for is worth more than the hotkey question it was scoped to.