Release oída 0.2.0: the listening server — unified gateway, MCP, host perception

Oída becomes the stack's main application: one process owning the MOSS
engines and exposing the gateway contract (oida/gateway/v0.2), the
host-perception path (oida/host-perception/v0.1) that routes, types, and
audits other models' hearings, the official FastMCP server (10 tools, 4
resources, 3 prompts; stdio + streamable HTTP at /mcp), the embedded
Akousmata library at /library/, lifecycle supervision (start/stop/status/
doctor/agent/gateway), and integrations for Hermes, Claude Code, Codex,
and Tailscale-served remote access.

Polish: /api index now lists the gateway and akousmata surfaces; gateway
manifest version single-sourced from oida.__version__; claim-mapper
docstring placed correctly; legacy JSON-RPC MCP shim marked deprecated;
README germ-URL default corrected; CHANGELOG dated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: emeisazam

CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
-## 0.2.0 - Unreleased
+## 0.2.0 - 2026-07-10
+
+- **Oída is now the complete listening distribution and gateway**: installing
+  it resolves AKOÚŌ (`akouo-contract`), Earworm's `akousma`, and the Akousmata
+  navigator. One FastAPI process exposes the agent/dashboard, REST gateway,
+  official streamable HTTP MCP at `/mcp`, and full library at `/library/`.
+- **Provider-neutral host perception**: `oida/gateway/v0.2` accepts either
+  Oída-owned audio (`/gateway/listen`) or a declared report from an
+  audio-capable host (`/gateway/harness`). Host-model observations cannot be
+  silently promoted to DSP measurements; apparatus limits and unknowns remain
+  explicit, while MOSS keeps its 16 kHz mono restrictions.
+- **Gateway lifecycle and local adapters**: `start`, `stop`, `status`, `doctor`,
+  `agent`, `gateway`, and `integrate` commands manage a singleton daemon and
+  install bundled Hermes, Codex, Claude, and Tailscale-remote integrations.
+  MCP processes ensure or reuse the gateway and pin the active Python runtime.
+- **Earworm on every pass, durable memory only by consent**: session-scoped
+  Earworm context is emitted for all gateway listens and host harness passes;
+  Akousmata writes still require an explicit remember action.
 
 - **Akousmata history embedded in the dashboard**: a new left-side
   "Akousmata" section browses the shared store natively inside oída (search,

README.md

@@ -1,10 +1,12 @@
 # oída
 
-`oida` is a local listening agent for machine ears. It listens to audio files,
-the microphone, and the computer's own output, routes sound through MOSS-Audio
-and AKOÚŌ listening paths, extracts measured signal features, and normalizes
-everything into listening events that can be remembered, questioned, handed to
-germ as akousmata, or explored in the Sonic Field wiki.
+`oida` is the unified local agentic listening stack: the AKOÚŌ listening
+harness, Earworm provenance and memory protocol, and Akousmata listening
+library behind one agent, CLI, gateway, and install. It can listen through its
+own optional local engine (including MOSS-Audio plus deterministic DSP), or it
+can harness the audio perception already produced by Hermes, Codex, Claude, or
+another audio-input-capable host. Both paths produce the same accountable
+AKOÚŌ claims, Earworm session context, and optional durable Akousmata memory.
 
 This project was previously named **AEAR**, then **hmm**; it is now **oída**.
 The Python package and primary CLI are `oida`; `hmm` and `aear` remain as
@@ -14,6 +16,22 @@ name **oída**.
 
 ## What Is Implemented
 
+- **Unified gateway contract** (`oida/gateway/v0.2`) with two honest perception
+  paths: Oída-owned audio through `POST /gateway/listen`, and host-owned model
+  perception through `POST /gateway/harness`. `GET /gateway` advertises the
+  installed AKOÚŌ, Earworm, and Akousmata contracts; `GET
+  /gateway/schema/host-perception` publishes the host envelope.
+- **One lifecycle**: `oida start` ensures a singleton background gateway,
+  `oida agent` starts it and opens the listening agent, and every stdio MCP
+  adapter can ensure/reuse that gateway itself. The same process serves the
+  dashboard, REST API, streamable HTTP MCP at `/mcp`, and the complete
+  Akousmata navigator at `/library/`.
+- **Local host integrations** installed by `oida integrate`: a native Hermes
+  plugin, Codex and Claude plugins, and a mobile-responsive private Tailscale
+  surface. Their generated MCP configs are pinned to the active Oída runtime,
+  so they do not depend on shell `PATH` or require a second app. Host adapters
+  start the gateway without prewarming MOSS; the host-perception path stays
+  lightweight until Oída-owned listening actually needs the local model.
 - FastAPI daemon (default `127.0.0.1:8765`) with task endpoints
   (`/transcribe`, `/events`, `/caption`, `/speech`, `/music`, `/qa`, `/think`,
   `/report`), the listening-event pipeline (`/listen-event`,
@@ -45,7 +63,7 @@ name **oída**.
 - **germ handoff** (shared akousmata store): after a listen, three actions —
   *Sound*, *Prompt*, *Lineage* — persist the listen as an **akousma** in the
   shared store (`~/Documents/SFL/akousmata`, via earworm's `py-akousma`) and
-  deep-link germ (`OIDA_GERM_URL`, default `http://127.0.0.1:5178/import`).
+  deep-link germ's `/import` route (`OIDA_GERM_URL`, default `http://127.0.0.1:5178`).
   Opt-in song identification (`OIDA_SONGID=1`, ShazamIO) enriches the record's
   `extensions.songid`.
 - **Sonic Field bridge**: "Explore in the wiki" searches the wiki, topics,
@@ -68,27 +86,45 @@ name **oída**.
   controls float just outside the box and appear on hover. Global hotkeys
   default to ⌃⌥L (listen) and ⌃⌥H (show/hide it).
 - CLI (`oida listen/live/background/memory/chat/sweep/corpus-qa/bench`), `ear`
-  and `akoe` helper CLIs, and an MCP server exposing `oida_*` tools (legacy
-  `hmm_*`/`aear_*`/`ear_*` aliases kept).
-- 113 unit tests that run without model weights.
+  and `akoe` helper CLIs, and an official MCP server exposing compact
+  `oida_*` listening, harness, memory, and live tools (legacy aliases kept on
+  the HTTP compatibility surface).
+- A dependency-light test suite that runs without model weights.
 
 ## Quick Start
 
-Prerequisites: Python 3.12+, `uv`, `ffmpeg` for non-WAV uploads or browser
-recordings, and a sibling checkout of `earworm` (the `akousma` dependency is an
-editable path source at `../earworm/packages/py-akousma`).
+Prerequisites: Python 3.12+, `uv`, and `ffmpeg` for non-WAV uploads or browser
+recordings. From this source workspace, one sync installs Oída together with
+the canonical AKOÚŌ, Earworm/akousma, and Akousmata packages:
 
 ```bash
-uv sync --extra dev
+uv sync --extra dev --extra moss
 ```
 
-Run the daemon (MOSS-Audio on Apple Silicon is the default profile):
+Start the singleton gateway, then open the agent or library:
 
 ```bash
-uv run oida --host 127.0.0.1 --port 8765   # add --profile stub for a model-free dev run
+uv run oida start                         # add --profile stub for model-free use
+uv run oida agent
+uv run oida agent --library
 ```
 
-Open the dashboard at `http://127.0.0.1:8765`.
+`oida` or `oida serve` still runs the same system in the foreground. The local
+dashboard is `http://127.0.0.1:8765`, the library is `/library/`, REST gateway
+discovery is `/gateway`, and streamable HTTP MCP is `/mcp`.
+
+Install the local adapters (each host can then start/reuse Oída automatically):
+
+```bash
+uv run oida integrate hermes
+uv run oida integrate codex
+uv run oida integrate claude
+uv run oida integrate remote --serve     # private responsive UI via Tailscale
+uv run oida doctor
+```
+
+No native iOS or cloud service is required: open the reported Tailscale URL on
+the phone to use it as the microphone, speaker, screen, and remote control.
 
 Generate a normalized listening event:
 
@@ -98,6 +134,11 @@ curl -s http://127.0.0.1:8765/listen-event \
   -d '{"path":"/path/to/clip.wav","route_preset":"basic"}'
 ```
 
+An audio-capable host can keep perception in its own model and send a declared
+report to `/gateway/harness`; see [the gateway contract](docs/gateway-contract.md)
+for the schema and examples. MOSS is therefore an optimized local backend, not
+a requirement for the harness path.
+
 Routed local session, live ring buffer, and background runtime:
 
 ```bash
@@ -204,7 +245,11 @@ akousmata store is written only by the explicit germ handoff actions.
   (`PLAN.md` keeps the historical OIDA phases).
 - `docs/release-readiness.md` — what `scripts/run_local_checks.sh release`
   validates.
+- `docs/gateway-contract.md` — lifecycle, host-perception envelope, and local
+  integration boundaries.
+- `integrations/` — the bundled Hermes, Codex, Claude, and remote adapters.
 - CI (`.github/workflows/ci.yml`) runs pytest, compileall, a JS syntax check,
   the Swift build (including strict concurrency), packaging, and the stub
-  daemon release smoke. The `akousma` path dependency requires `earworm`
-  checked out as a sibling.
+  daemon release smoke. Development uses canonical sibling sources; the Oída
+  distribution declares them as versioned dependencies so they are installed
+  as one stack rather than copied into divergent forks.

docs/architecture/current-state.md

@@ -1,8 +1,21 @@
 # Current Architecture: `oida` Base
 
-This document maps the current OIDA codebase that `oida` is being built from.
-The repository is already a working local listening daemon and AKOÚŌ harness;
-the next stage should wrap and extend these paths rather than replace them.
+This document maps the current Oída unified listening stack. Oída is both a
+listening agent and a harness layer for other audio-capable agents.
+
+## Unified Stack And Gateway
+
+One Oída installation resolves the canonical AKOÚŌ contract package,
+Earworm/akousma protocol package, and Akousmata navigator. One managed server
+exposes four coordinated surfaces: the Oída agent/dashboard, the
+`oida/gateway/v0.2` REST contract, official MCP over stdio or `/mcp`, and the
+Akousmata app mounted at `/library/`.
+
+There are two perception paths. `oida_owned` sends accessible audio through
+Oída's selected engine and DSP. `host_supplied` accepts a model report from an
+audio-input-capable host, preserves that host's apparatus declaration, and
+routes its observations through the same AKOÚŌ and Earworm layers. MOSS-Audio
+is the optimized local model backend, not a gateway requirement.
 
 ## Project Shape
 
@@ -23,21 +36,20 @@ the next stage should wrap and extend these paths rather than replace them.
 - `oida/MOSS-Audio/` and `oida/weights/` are local model/runtime assets used by
   the Mac MPS profile. They are not app source.
 
-The Python package remains `oida` internally for compatibility. The public app
-identity is moving to lowercase `oida`, with `oida` kept as a legacy alias.
+The Python package and CLI are `oida`; the accented public identity is **oída**.
+The historical `hmm` and `aear` commands remain compatibility aliases.
 
 ## Current Request Flow
 
 ```text
-dashboard / CLI / MCP
-  -> FastAPI endpoint in oida.server
-  -> oida.reporting task function
-  -> MossEngine adapter
-  -> MOSS-Audio output parsing
-  -> DSP feature extraction
+dashboard / CLI / MCP / host plugin
+  -> Oída gateway router
+  -> Oída-owned audio: reporting -> selected audio engine + DSP
+     OR host-owned perception: declared host report + apparatus
   -> PerceptionReport schema
   -> AKOÚŌ command output / claim mapping
-  -> dashboard render, CLI journal, or JSON response
+  -> Earworm session context (+ explicit Akousmata remember when requested)
+  -> dashboard, CLI, host agent, library, journal, or JSON response
 ```
 
 ## Audio File Flow

docs/gateway-contract.md

@@ -0,0 +1,80 @@
+# Oída gateway contract
+
+Oída is both a listening agent and a local listening layer for other agents.
+Installing Oída installs and exposes the complete stack: AKOÚŌ routing and
+claim discipline, Earworm event/provenance envelopes, and the Akousmata store
+and navigator.
+
+The stable gateway contract is `oida/gateway/v0.2`. It supports two paths:
+
+1. **Oída-owned perception** — pass Oída a local audio path. Its configured
+   engine (MOSS-Audio when available, DSP-only stub otherwise) performs the
+   perceptual passes. Oída returns the perception report, AKOÚŌ command output,
+   normalized listening event, and an optional memory trace.
+2. **Host-supplied perception** — an audio-capable Hermes, Codex, Claude, or
+   generic host describes what its active model heard using
+   `oida/host-perception/v0.1`. Oída does not run MOSS again. It applies the
+   same router, evidence permissions, claim taxonomy, Earworm provenance, and
+   Akousmata memory flow.
+
+Host perception must declare its apparatus when known. Sample rate, channel
+count, bandwidth, calibration, preprocessing, and blind spots determine which
+claims can be supported. An undeclared apparatus is accepted but explicitly
+marked undetermined. Model output can never become a `measured` claim merely
+because the model used a number; measurements need DSP, metadata, a measuring
+tool, or a declared human measurement.
+
+## Lifecycle
+
+- `oida` or `oida serve` runs the agent, REST gateway, dashboard, and mounted
+  Akousmata navigator in one process.
+- `oida start` ensures the singleton local gateway is running in the background.
+- `oida gateway --stdio --ensure-daemon` is the MCP command for local agents.
+- `oida agent` ensures the gateway and opens its local interface.
+- `oida status`, `oida doctor`, and `oida stop` inspect or control the managed
+  gateway.
+
+Hermes, Codex, and Claude integrations always invoke the stdio gateway command,
+so they can start Oída when needed without loading a second MOSS model. A
+running daemon is reused. The local remote surface uses the same process and is
+intended for an operator-configured private network such as Tailscale; it is
+not a cloud application.
+
+## Host input example
+
+```json
+{
+  "contract": "oida/host-perception/v0.1",
+  "host": {
+    "id": "codex",
+    "model": "audio-capable-model",
+    "session_id": "session-123",
+    "audio_input_capable": true
+  },
+  "source": {
+    "label": "attached field recording",
+    "type": "file",
+    "duration_s": 18.4,
+    "audio_available_to_oida": false
+  },
+  "apparatus": {
+    "substrate": "host_audio_model",
+    "sample_rate_hz": 48000,
+    "channels": 2,
+    "bandwidth_limit_hz": 24000,
+    "known_blind_spots": ["The host does not expose its resampling path."]
+  },
+  "observations": [
+    {
+      "statement": "A repeating metallic impact is audible.",
+      "category": "heard",
+      "confidence": "medium",
+      "source": "model",
+      "time_range": {"start_s": 2.1, "end_s": 7.8}
+    }
+  ],
+  "uncertainty": ["The source object cannot be identified from audio alone."]
+}
+```
+
+See `oida/schemas/host-perception.schema.json` for the complete input schema.

harness/akouo/command.py

@@ -11,9 +11,18 @@
 
 
 def build_apparatus(report: dict[str, Any] | None = None) -> dict[str, Any]:
-    """AKOÚŌ v0.6 apparatus declaration for the oída stack: name the substrate and
-    its structural blind spots so claim limits derive from the declared apparatus."""
+    """AKOÚŌ apparatus declaration for Oída or a host audio model."""
     report = report if isinstance(report, dict) else {}
+    declared = report.get("apparatus") if isinstance(report.get("apparatus"), dict) else None
+    if declared:
+        apparatus = dict(declared)
+        apparatus.setdefault("substrate", "host_audio_model")
+        apparatus.setdefault("perception_sources", ["host-supplied audio perception"])
+        apparatus.setdefault(
+            "known_blind_spots",
+            ["The host did not declare complete acoustic preprocessing and calibration details."],
+        )
+        return apparatus
     engine = report.get("engine") if isinstance(report.get("engine"), dict) else {}
     perception_sources = ["oida DSP feature block (deterministic measurement)"]
     for key, label in (
@@ -54,18 +63,20 @@ def build_listening_output(
     recommended_next_mode: str = "undetermined",
     report: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
+    apparatus = build_apparatus(report)
+    sources = ", ".join(str(source) for source in apparatus.get("perception_sources", [])[:2]) or "machine perception"
     risks = empty_risks()
-    risks["hallucination"].append("MOSS-Audio can overstate acoustic evidence; retain time anchors and uncertainty notes.")
+    risks["hallucination"].append("Audio models can overstate acoustic evidence; retain time anchors and uncertainty notes.")
     risks["over_identification"].append("Source, speaker identity, age, accent, and emotion claims require caution.")
     mediations = empty_mediations()
-    mediations["technical"].append("MOSS-Audio receives 16 kHz mono audio; DSP supplies measured signal features.")
-    mediations["computational"].append("PerceptionReport evidence is model output plus deterministic DSP, not direct human listening.")
+    mediations["technical"].append(f"Declared perception apparatus: {sources}.")
+    mediations["computational"].append("PerceptionReport evidence is model output plus any declared measurements, not direct human listening.")
     return {
         "object_listened_to": object_listened_to,
         "input_type": "model_output",
         "listening_mode": mode,
         "akouo_version": AKOUO_OUTPUT_VERSION,
-        "apparatus": build_apparatus(report),
+        "apparatus": apparatus,
         "listener": {"type": "agent", "process": "agent_automated"},
         "listening_claims": claims,
         "what_appears": summarize_visible_claims(claims),
@@ -99,7 +110,7 @@ def build_command_output(report: dict[str, Any], command: str = "/listen", quest
     return {
         "command": command,
         "object_listened_to": object_listened_to,
-        "input_type": "audio_file",
+        "input_type": "model_output" if report.get("host") else "audio_file",
         "akouo_version": AKOUO_OUTPUT_VERSION,
         "skills_called": skills_called,
         "execution_order": skills_called,
@@ -108,8 +119,8 @@ def build_command_output(report: dict[str, Any], command: str = "/listen", quest
         "synthesis": synthesize_claims(claims, command),
         "claim_summary": claims,
         "risks": [
-            "MOSS captions and paralinguistics are machine-heard evidence, not measurements.",
-            "Contradictions between DSP and MOSS remain undetermined.",
+            "Model captions and paralinguistics are machine-heard evidence, not measurements.",
+            "Contradictions between declared measurements and model perception remain undetermined.",
         ],
         "recommended_next_mode": route.recommended_next_mode,
     }

harness/akouo/loader.py

@@ -21,6 +21,14 @@ def default_akouo_root() -> Path:
     for candidate in DEFAULT_AKOUO_CANDIDATES:
         if candidate and candidate.expanduser().exists():
             return candidate.expanduser().resolve()
+    try:
+        from akouo_contract import root as installed_root
+
+        packaged = installed_root()
+        if packaged.exists():
+            return packaged
+    except (ImportError, OSError):
+        pass
     return Path.home() / "Documents" / "SFL" / "akouo"