[simeszi001]

Unexpected activations are difficult to attribute from wake logs alone. This adds opt-in, bounded local diagnostics that correlate model crossings with microphone/model settings and distinguish button/API requests and follow-ups.

Depends on ygelfand/libcountertop#2. Merge the library change first. For reproducible review builds this branch pins the public library fork to its immutable PR commit; replace that temporary remote dependency with the merged upstream version before merging this PR. There is no local filesystem replace or dependency on a developer's checkout.

Behavior

• Off by default and after restart. Explicit activation is limited to 24 hours, 100 model captures and 256 fixed non-audio markers.
• Up to 5 seconds of pre-roll + 1 second of post-roll from the existing detector PCM stream, with model-file/WAV hashes, scores and relevant microphone settings. No changes to detection thresholds, wake words, gain or AEC.
• Bounded pending/write queues; audio callbacks do not wait on disk writes. Known frame gaps, pause/mute and model changes discard incomplete captures. Stop clears pending audio; completed queued writes may finish. Shutdown clears queued audio.
• Local files with restrictive modes, a 64 MiB storage budget, no overwrites or automatic deletion of existing history, and observation disabled on storage failure.
• Three response-capable actions for control, event listing and paginated retrieval through the existing paired native API / authenticated web action interface. No extra listener or public download route.

The English guide documents API arguments, base64 page reconstruction, hash verification, consent, access boundaries, retention and diagnostic limitations. Recording expiry does not delete saved clips. Authenticated clients can explicitly retrieve audio; there is no automatic cloud upload. No raw household recordings, device addresses, room bindings, credentials, deployment helpers, firmware version overrides or listener-policy changes are included.

Validation

• go test ./..., go vet ./..., and go test -race ./...
• Linux ARMv7 and ARM64 Echo Dot (board_biscuit) builds, plus ARM/noasm
• golangci-lint 2.12.2 formatting, default lint and board_biscuit lint
• Synthetic tests for exact clip boundaries, disabled/muted operation, expiry and limits, gaps/model changes, queue pressure, in-flight write/start exclusion, storage failures, restart, symlink/path/page rejection, WAV reconstruction/hashes, concurrent controls and action validation

An earlier downstream variant was exercised on seven Echo Dot 2 devices; this cleaned-up PR revision has not been flashed or acoustically retested. The current evidence is automated testing and cross-compilation, not a claim of improved wake accuracy. Android NDK/Show payload builds were not run locally; those remain for upstream CI/hardware coverage.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[ygelfand]

this is definitely interesting, most if not all of this pr belongs in the library itself, not in echolocal, as it is device agnostic. that will remove the need for the go changes. Also recommend using go.work, to avoid having to pin to forks if that helps you. the giant llm generated readme file does not fit out code style here. The bigger issue is this also appears to install hooks at all times, so will have a performance impact at all times (not sure how much though). I can clean it up and get this into your lib pr if you prefer.