Checkpoint: in-flight signal listener, sonicfield bridge, floating panel & mic tap

Captures ~68 files of work-in-progress (new signal_listener/sonicfield/raw_audio
modules, macOS FloatingPanel + MicTapManager + FloatingListenerView, project meta
files) as a clean base before the hmm→oída rename.

Author: emeisazam

.env.example

@@ -1,6 +1,9 @@
-AEAR_ENGINE_PROFILE=stub
+HMM_ENGINE_PROFILE=mac-mps
+HMM_AUDIO_DIR=~/Documents/hmm/audio
+HMM_MOSS_PREWARM=1
+HMM_SONICFIELD_ROOT=~/Documents/sonicfield
 AEAR_SERVER_URL=http://127.0.0.1:8765
-AEAR_AKOUO_ROOT=/path/to/akouo
+AEAR_AKOUO_ROOT=~/Documents/sfl/akouo
 AEAR_MOSS_AUDIO_REPO=./MOSS-Audio
 AEAR_MOSS_INSTRUCT_MODEL=./weights/MOSS-Audio-4B-Instruct
 AEAR_MOSS_THINKING_MODEL=./weights/MOSS-Audio-4B-Thinking

CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## 0.2.0 - Unreleased
+
+- Made `mac-mps` the default engine everywhere (daemon, macOS shell, env
+  examples); the daemon prewarms MOSS-Audio-4B-Instruct in the background and
+  reports readiness at `/engine/status` (`HMM_MOSS_PREWARM=0` disables).
+- Added the deterministic **signal listener** (`aear/signal_listener.py`):
+  DSP-only classification (silence / speech-like / music-like / tonal /
+  percussive / noise / ambient), honest captions, and inferred hypotheses with
+  numeric bases. Perception never falls back to placeholder text; without a
+  model the evidence level honestly stays `measured_signal`.
+- Route presets now scope MOSS passes (`moss_passes`): Basic runs one caption
+  pass (seconds, not minutes), Signal is DSP-only, Speech runs
+  transcribe+speech, and the new **Deep** preset runs the full report.
+- Chunked mac-mps inference at 45 s per pass (`HMM_MOSS_CHUNK_SECONDS`), with a
+  decode-degeneracy guard that discards token-soup output instead of letting it
+  become claims, and a tokenizer-safe decode fallback.
+- Added Sonic Field bridge (`aear/sonicfield.py`, `/sonicfield/*`): after a
+  listen, "Explore in the wiki" searches the wiki/lexicon, topics, journal,
+  93k-item library, paths, research, notes, and labs for related concepts,
+  with taxonomy alias normalization and Finder reveal.
+- Added `/events/stream` (SSE) so every surface mirrors one daemon state, and
+  `/background/capture-request` so the web dashboard can ask the native shell
+  to capture system audio.
+- Default audio directory moved to `~/Documents/hmm/audio`
+  (`HMM_AUDIO_DIR`); captures, uploads, and fixtures land there.
+- Rebuilt the dashboard as one Listen surface (source + presets + skill
+  manager), claims rendered by AKOUO category, memory and history cards, and a
+  soft-minimal visual system; removed the floating spectral agent, its
+  settings, RMS/peak meters, and the task tabs.
+- Rebuilt the macOS shell: the main window embeds the dashboard (WKWebView) so
+  web and app never diverge; the floating listener is a minimal always-on-top
+  panel with live signal, latest reading, and one Listen action; global
+  hotkeys default to ⌃⌥L (listen) and ⌃⌥H (show/hide listener); the shell
+  auto-starts the daemon and system tap and claims dashboard capture requests.
+
+## 0.1.0 - Unreleased
+
+- Added platform data directory support through `HMM_DATA_DIR` / `AEAR_DATA_DIR`
+  with macOS default `~/Library/Application Support/hmm`.
+- Disabled implicit Hugging Face hub model fallback unless explicitly enabled.
+- Added bearer-token enforcement for wildcard/LAN daemon binds.
+- Added raw-audio status and wipe endpoints for local upload/live-buffer
+  retention, including pre-data-dir checkout `uploads/` recordings via the
+  `include_legacy` wipe option (the dashboard Wipe raw audio button sets it).
+- Bounded in-memory stopped live sessions to the most recent few.
+- Added Earworm-compatible Akousmata trace/session/context metadata.
+- Updated AKOUO harness routing for the v0.5 public command contract and
+  derived evidence levels.
+- Reduced long-audio memory pressure by bounded DSP inspection and per-chunk
+  source reads.
+- Added release/security/contribution/citation metadata.

CITATION.cff

@@ -0,0 +1,17 @@
+cff-version: 1.2.0
+title: "hmm: local listening agent for the Listening Stack"
+message: "If you use hmm in research, please cite the software and the Listening Stack paper."
+type: software
+authors:
+  - name: "Sonic Field Labs"
+version: 0.1.0
+date-released: 2026-07-02
+license: Apache-2.0
+repository-code: "https://github.com/sonicfieldlabs/hmm"
+preferred-citation:
+  type: article
+  title: "The Listening Stack: Agentic Sonic Computation for Hybrid Listening Ecologies"
+  authors:
+    - family-names: "Isaza"
+      given-names: "eme"
+  year: 2026

CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+`hmm` is a local-first listening agent. Changes should preserve four contracts:
+
+- Raw audio never leaves the operator machine by default.
+- Raw audio retention and deletion paths stay explicit and testable.
+- MOSS-Audio output is perception evidence, not final truth.
+- AKOUO claim categories remain separate: heard, measured, inferred,
+  interpreted, speculative, undetermined.
+
+## Local Checks
+
+```bash
+uv sync --extra dev
+uv run python -m unittest discover -s tests
+uv run pytest
+```
+
+For release smoke checks, start the stub daemon and run:
+
+```bash
+scripts/run_local_checks.sh release
+```
+
+## Dependencies
+
+Keep runtime dependencies small. Network-capable packages should be dev-only
+unless the daemon itself needs them at runtime.

LICENSE

@@ -155,3 +155,19 @@ such Contributor by reason of your accepting any such warranty or additional
 liability.
 
 END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+Copyright 2026 Sonic Field Labs
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

NOTICE

@@ -0,0 +1,12 @@
+hmm
+Copyright 2026 Sonic Field Labs
+
+This product includes software developed by Sonic Field Labs.
+
+hmm integrates with MOSS-Audio model code and weights when the operator installs
+them separately. MOSS-Audio is developed by OpenMOSS / MOSI.AI and is not
+redistributed in this repository.
+
+AKOUO and Earworm are Sonic Field Labs listening-stack companion projects. Their
+local checkouts or released packages are referenced as optional integration
+surfaces; this repository embeds only hmm-specific glue code and schemas.

PLAN.md

@@ -1,6 +1,8 @@
-# AEAR Implementation Plan
+# hmm Implementation Plan (historical AEAR phases)
 
-This file tracks the `mossagent.md` plan as implemented in this repository.
+This file tracks the `mossagent.md` plan as implemented in this repository,
+written under the project's earlier name AEAR and kept as a phase log. For the
+current architecture map, see `docs/architecture/current-state.md`.
 
 ## Phase 0 - Feasibility Spike
 

README.md

@@ -50,16 +50,19 @@ New user-facing commands and UI copy use lowercase `hmm`.
 
 ## Quick Start
 
+Prerequisites: Python 3.12+, `uv`, and `ffmpeg` for non-WAV uploads or browser
+recordings.
+
 Install dependencies:
 
 ```bash
-uv sync
+uv sync --extra dev
 ```
 
-Run the daemon in development mode with the local stub engine:
+Run the daemon (MOSS-Audio on Apple Silicon is the default profile):
 
 ```bash
-uv run hmm --profile stub --host 127.0.0.1 --port 8765
+uv run hmm --host 127.0.0.1 --port 8765  # add --profile stub for a model-free dev run
 ```
 
 Open the dashboard:
@@ -71,9 +74,10 @@ http://127.0.0.1:8765
 Generate a normalized listening event:
 
 ```bash
+uv run python -c "import numpy as np, soundfile as sf; t=np.arange(16000)/16000; sf.write('/tmp/hmm-tone.wav',(0.15*np.sin(2*np.pi*440*t)).astype('float32'),16000)"
 curl -s http://127.0.0.1:8765/listen-event \
   -H 'content-type: application/json' \
-  -d '{"path":"MOSS-Audio/test/test_en.mp3","route_preset":"basic"}'
+  -d '{"path":"/tmp/hmm-tone.wav","route_preset":"basic"}'
 ```
 
 Run a routed local session and write `sessions/<stamp>-<slug>/`:
@@ -112,8 +116,8 @@ apps/macos/script/build_and_run.sh
 
 The shell stages `apps/macos/dist/hmm.app`, adds a menu bar extra, opens the
 dashboard, triggers background quick capture, and exposes an optional global
-hotkey in Settings. If the daemon is offline, the shell can start a local
-development daemon with `uv run hmm --profile stub`. Launch at login is
+hotkey in Settings. If the daemon is offline, the shell starts one automatically with the
+`mac-mps` profile. Launch at login is
 available in Settings and is never enabled automatically.
 
 The shell also includes an explicit native system-output signal tap. It uses
@@ -127,6 +131,13 @@ Native source-route profiles are exposed at `/native/system-audio/routes`; the
 current route is `display_mix`, meaning the selected display's system mix with
 the hmm process excluded.
 
+Raw browser uploads and live chunks are stored under the configured hmm data
+directory, not the source checkout. Inspect them with `/raw-audio/status` and
+delete them with `/raw-audio/wipe`; the dashboard exposes this as Wipe raw
+audio. Recordings written by older builds into the checkout's `uploads/` are
+reported under the status `legacy_*` fields and deleted when the wipe request
+sets `include_legacy` (the dashboard button does).
+
 Package a local unsigned app archive:
 
 ```bash
@@ -153,10 +164,10 @@ Existing listening events can be rerun through a different preset with
 new audio. Rerun responses include a conservative route comparison over route
 ids, summary changes, warnings, deterministic DSP deltas, and applied comparison
 filters. The daemon also keeps a bounded recent-result list at
-`/background/history`, persists derived event JSON to
-`sessions/recent-results.json`, and excludes incognito events from that durable
-history by default. Pinned recent results are persisted separately from the
-rolling recent list, and `/background/history/export`, `/background/history/pin`,
+`/background/history`, persists derived event JSON under the configured hmm data
+directory, and excludes incognito events from that durable history by default.
+Pinned recent results are persisted separately from the rolling recent list, and
+`/background/history/export`, `/background/history/pin`,
 `/background/history/batch-pin`, `/background/history/archive`, and
 `/background/history/clear` expose derived-history export, pin/unpin, batch
 pinning, archive-to-file, and explicit clear controls without copying raw audio.
@@ -236,7 +247,8 @@ left for the desktop app-shell phase.
 Run tests that do not require downloaded model weights:
 
 ```bash
-python3 -m unittest discover -s tests
+uv run python -m unittest discover -s tests
+uv run pytest
 ```
 
 ## Real MOSS-Audio Profile
@@ -269,6 +281,12 @@ and sets `audio_input_mask = input_ids == processor.audio_token_id`.
 `AEAR_MOSS_RESIDENT=single` hot-swaps Instruct and Thinking instead of keeping
 both 4B models resident.
 
+`hmm` will not silently download model code or weights. If the local `weights/`
+paths are absent, the `mac-mps` profile falls back to the stub engine unless
+`AEAR_REQUIRE_MODEL=1` is set, and Hugging Face hub lookup is refused unless
+`HMM_ALLOW_HF_HUB=1` or `AEAR_ALLOW_HF_HUB=1` is set. `HF_HUB_OFFLINE=1` always
+keeps hub lookup disabled.
+
 ## CUDA/SGLang Profile
 
 Start the official MOSS-Audio SGLang fork separately, then point `hmm` at it:
@@ -283,12 +301,21 @@ Thinking budgets are forwarded through `custom_params.thinking_budget`.
 ## Privacy Defaults
 
 `hmm` is local-first. The daemon binds to `127.0.0.1` by default and does not
-upload audio. Background-style buffers are ephemeral by product policy, but the
-current browser live path still writes temporary chunks to local `uploads/`
-because browser `MediaRecorder` sends encoded files to the daemon. Quick live
-captures are labeled with `raw_audio_policy: temp`. Native system-output temp
-captures use a separate retention policy under `native_temp_audio_retention`
-and cleanup only targets files matching the native capture naming pattern.
+upload audio. If you bind to `0.0.0.0` or `::`, the daemon refuses to start
+unless `HMM_AUTH_TOKEN` or `AEAR_AUTH_TOKEN` is set; clients then send
+`Authorization: Bearer <token>`.
+
+Persistent local data defaults to `~/Library/Application Support/hmm` on macOS,
+or `$XDG_DATA_HOME/hmm` / `~/.local/share/hmm` elsewhere. Override it with
+`HMM_DATA_DIR` or `AEAR_DATA_DIR`.
+
+Background-style buffers are ephemeral by product policy, but browser live
+capture still writes temporary chunks to the data-dir `uploads/` because
+`MediaRecorder` sends encoded files to the daemon. Quick live captures are
+labeled with `raw_audio_policy: temp`. Native system-output temp captures use a
+separate retention policy under `native_temp_audio_retention`, raw uploads use
+`upload_audio_retention`, and `/raw-audio/wipe` removes all upload/live-buffer
+raw audio on request.
 
 Akousmata memory is explicit: events are saved only when the user calls
 `/memory/remember` or uses the dashboard remember action. File-based listening

SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are accepted against the current `main` branch until the first
+public release tag is cut.
+
+## Reporting A Vulnerability
+
+Please report security issues privately to Sonic Field Labs before public
+disclosure. Include the affected commit, local configuration, reproduction steps,
+and whether raw audio or private listening traces can be exposed.
+
+## Local-First Boundaries
+
+`hmm` binds to `127.0.0.1` by default. Wildcard or LAN binds are refused unless
+`HMM_AUTH_TOKEN` or `AEAR_AUTH_TOKEN` is set, and token-protected clients must
+send `Authorization: Bearer <token>`.
+
+MOSS-Audio Hugging Face model lookup is disabled by default. Download weights
+into `weights/` or set `HMM_ALLOW_HF_HUB=1` / `AEAR_ALLOW_HF_HUB=1` explicitly.
+`HF_HUB_OFFLINE=1` always disables hub lookup.