sessionvoice 0.3.2__tar.gz → 0.4.0__tar.gz

{sessionvoice-0.3.2/src/sessionvoice.egg-info → sessionvoice-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sessionvoice
-Version: 0.3.2
+Version: 0.4.0
 Summary: One listening engine for coding agents and the Delta bot: Apple / Nemotron / whisper -> one event stream -> VAD -> turns
 Author-email: Mike Bailey <mike@sessionkit.ai>
 License-Expression: AGPL-3.0-or-later
@@ -72,7 +72,7 @@ streams transcription, and decides when the speaker has finished.
   for a while.
 - **Barge-in:** on headphones or a call, talk over the assistant and its voice
   dips at once; a couple of your own words, or "stop", cut it off
-  ([barge-in](docs/barge-in.md)).
+  ([barge-in](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/barge-in.md)).
 
 ## Requirements
 
@@ -82,19 +82,21 @@ streams transcription, and decides when the speaker has finished.
 - [ ] Windows
 
 What sessionvoice depends on, what needs each one, and how to upgrade it:
-[dependencies](docs/dependencies.md).
+[dependencies](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/dependencies.md).
 
 ## Components
 
 The engine above is the core. Around it, these parts make it an always-on
-pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
+pair of ears on a Mac (depth in [docs/architecture.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/architecture.md)):
 
 - **Capture** (`src/ears/listen`): `ears.listen capture` reads one input
   device and writes every partial, turn and heartbeat to the **heard log**
   (`src/ears/heard.py`):
-  `<home>/logs/conversations/heard_YYYY-MM-DD.jsonl`, where `<home>` is
-  `~/.voicemode` on a host that already keeps it there, else
-  `~/.sessionvoice` ([docs/logs.md](docs/logs.md#sessionvoices-home)).
+  `<root>/logs/conversations/heard_YYYY-MM-DD.jsonl`, where `<root>` is the
+  state root: `~/.sessionkit/voice/state` on a new host, or the old
+  `~/.sessionvoice` or `~/.voicemode` on a host that already keeps its heard
+  log there ([docs/logs.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/logs.md#the-state-root)).
+  `ears home state-dir` prints it.
   On a fresh host that also runs VoiceMode's `converse` as a heard guest,
   set `SESSIONVOICE_HOME=~/.voicemode` (or `VOICEMODE_BASE_DIR`), so that
   both write one log.
@@ -128,9 +130,11 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
 - **Sounds** (`keeper/ears-sounds.py`, launchd `dev.sessionkit.voice.ears-sounds`):
   a short sound in the user's ears when the ears log an event, so they know
   they were heard. Its partner, `keeper/mouth-sounds.py`
-  (`dev.sessionkit.voice.mouth-sounds`), plays the mouth's cues. Opt-in:
-  `ears services install --only sounds` loads both, from an installed
-  package or a checkout; a bare install never does.
+  (`dev.sessionkit.voice.mouth-sounds`), plays the mouth's cues. A bare
+  `ears services install` loads both, from an installed package or a
+  checkout. From the first turn the ears' turn and partial ticks are on
+  (Settings turns them off), and so are the mouth's five cues
+  (`mouth-sounds.json` in the settings folder turns each off).
 - **Turn mail** (`keeper/ears-mail.py`, launchd `dev.sessionkit.voice.ears-mail`):
   mails each of the user's finished turns To and From
   `heard+room@<host>`, whatever input device the capture is following, with
@@ -159,6 +163,12 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
   label is dropped: the remaining words get `--speaker` (else
   `unknown@<host>`), never the seat whose echo was cut, and they can be a
   reply to that seat. A label naming anyone else is kept.
+  `Ears-Addressed` lists the seats a turn names, as `<seat>@<host>`, wherever
+  the name falls in the turn, plus `everyone` for "hey everyone":
+  `Ears-Addressed: everyone, ivy@<host>`. A seat is named by its `names` in
+  the wake file. The header carries names only, never the turn's words, and a
+  turn that names nobody has no `Ears-Addressed`. It goes on the room mail
+  only. [docs/ears.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/ears.md) gives the rules.
   `Ears-Echo` says a mouth line heard back through the mic was cut out of
   the turn. On the speakers the mic hears the mouth, so a line's
   words are cut wherever they sit in the user's turn: at its start (up to `3 + 5
@@ -187,6 +197,25 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
   have opened within 2 s of the line beginning, unless the turn is mostly
   the line. On the `ts − (t1 − t0)` estimate, only the first two guards
   apply. Numerals (`9%` for "nine percent") still slip past the word match.
+  `Ears-Said` names each session's own line the turn came after, so the
+  pager can keep that session's window open (its linger):
+  `Ears-Said: <session>@<host>=<end>, ...`. `<session>` is the full session
+  id on the line's `said` row, `<host>` the keeper's, and `<end>` that
+  row's `ts`, as it was written. Each session gets one entry: its newest line
+  that finished at or before the turn's `Ears-Start`, within 600 s. It
+  carries spoken lines only: a line on `lane: file` (a music bed or a sound
+  file) is left out, so a bed that ends after a line leaves that line the
+  session's newest. A line with `interest: zero`, or one cut before it
+  played a word (`played_s` 0), is left out. A line the user barged into after part of it played counts,
+  at its cut. Entries are sorted, and the header holds names and times,
+  never a line's words. It goes on the device mail and the `--to seats`
+  mail, never on a cut notice or a call turn; with no entry there is no
+  header.
+  `Ears-Film: playing` marks a turn the keeper heard while a film was
+  playing (`--kodi`: the state that holds `reply` and `light`), so the
+  pager can tell film dialogue from the user. It is a fact about the turn,
+  with one value, on the device mail only; with no film playing, or no
+  `--kodi`, there is no header. Kodi is asked at most once per turn.
 - **Waiter** (`bin/heard-first`): an agent blocks on the heard log
   until a line is for it, by `--rule`: its name in a partial or a
   turn (`partial:REGEX`, `turn:REGEX`), a reply to its last line
@@ -213,7 +242,7 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
 - **Speaker names** (`speakers/`, opt-in:
   `ears services install --only speakers`): a side-car tags each heard line
   with who spoke, in `speakers_YYYY-MM-DD.jsonl` beside the heard log, and
-  the waiters read it. See [speakers/README.md](speakers/README.md).
+  the waiters read it. See [speakers/README.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/speakers/README.md).
 
 ## Configuration
 
@@ -229,21 +258,22 @@ Three JSON settings files, each reread with no restart:
   read only their own file.
 
 Environment variables win over single keys (`EARS_RECORD` over `record`,
-`MOUTH_DEVICE` over `output`). `SESSIONVOICE_HOME` moves the home that holds
-the heard log and each part's state; by default it is `~/.sessionvoice`, or
-`~/.voicemode` on a host that already keeps its heard log there. The launch
-agents are in `~/Library/LaunchAgents/`.
+`MOUTH_DEVICE` over `output`). `SESSIONVOICE_HOME` moves the state root,
+which holds the heard log and each part's state; by default it is
+`~/.sessionkit/voice/state`, or the old `~/.sessionvoice` or `~/.voicemode` on
+a host that already keeps its heard log there. The launch agents are in
+`~/Library/LaunchAgents/`.
 
 Which files and which variables each part reads, and where each one lives:
-[docs/configuration.md](docs/configuration.md).
+[docs/configuration.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/configuration.md).
 Every key, its type and its default:
-[docs/settings.md](docs/settings.md).
+[docs/settings.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/settings.md).
 
 ## Logs
 
-- **The heard log:** `<home>/logs/conversations/heard_YYYY-MM-DD.jsonl`,
+- **The heard log:** `<root>/logs/conversations/heard_YYYY-MM-DD.jsonl`,
   one JSON line for each thing the ears heard and the mouth said, where
-  `<home>` is the home above. A new file starts each day.
+  `<root>` is the state root above (`ears home state-dir` prints it). A new file starts each day.
 - **The services' logs:** `~/.sessionkit/voice/log/` (`EARS_LOG_DIR` moves it).
   `ears-keeper.log` is what the keeper did (devices, restarts, calls, a
   deaf mic); `ears-keeper-capture.log` is the room capture's own output;
@@ -253,9 +283,9 @@ Every key, its type and its default:
 
 Follow one with `tail -F`, for example
 `tail -F ~/.sessionkit/voice/log/ears-keeper.log`, or today's heard log with
-`tail -F <home>/logs/conversations/heard_$(date +%F).jsonl`.
+`tail -F "$(ears home state-dir)/logs/conversations/heard_$(date +%F).jsonl"`.
 Every log file and what each line means:
-[docs/logs.md](docs/logs.md).
+[docs/logs.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/logs.md).
 
 - **Health:** `ears services status` prints one row per launch agent
   (`running, pid N`, `loaded, not running` or `not installed`; the
@@ -302,12 +332,13 @@ conversation either. On the host, run `talk pair` in a terminal and open the
 link it prints; `talk token --rotate` makes every browser pair again. Open talk
 at `http://127.0.0.1:<port>/`, never at `localhost`. The code is `src/talk/`.
 `ears services install --only talk` keeps it running as a launch agent
-(opt-in; a bare install never does).
+(opt-in; a bare install never does); add `--allow-host
+machine.example.ts.net` for a phone behind `tailscale serve`.
 
 In the kit's web page, Talk is a room: the kit's front door runs
 `talk serve --kit` on a unix socket and logs you in, so there is nothing to
 pair and you never run `--kit` by hand
-([docs/talk.md](docs/talk.md#in-the-kits-web-page)).
+([docs/talk.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/talk.md#in-the-kits-web-page)).
 
 ## Install
 
@@ -321,8 +352,7 @@ import that needs one fails naming it, as `pip install 'sessionvoice[EXTRA]'`.
 
     uv venv && uv pip install -e '.[all]'  # onnxruntime + mlx-audio
     ears install
-    ears services install --agent NAME     # the launch agents: mouth, keeper, mail
-    ears services install --only sounds    # opt-in: the ears and mouth sounds
+    ears services install --agent NAME     # the launch agents: mouth, keeper, mail, sounds
     ears services install --only talk      # opt-in: talk serve, the live view
 
 A phone-only Mac (for example one that runs a Delta bot, with no agent
@@ -332,7 +362,24 @@ an agent seat should be woken when you speak. Before it writes anything,
 install says how big the speech models are (about 2.9 GB, fetched once,
 after the speech server loads) and that the speech server runs as a login
 service; `--dry-run` prints the same line, and `--no-prefetch` leaves the
-download to the first call.
+download to the first call. `--no-prefetch` does not cover the Silero VAD
+model (2.3 MB): install still fetches a missing one, because the keeper
+cannot hear without it.
+
+A fresh install leaves the room's ear off. To turn it on now, and check the
+microphone while you are at the Mac:
+
+    ears services install --agent NAME --listen
+
+- Typing `--listen` is the consent: it writes `"listen": true` to `ears.json`
+  before the keeper loads.
+- macOS asks to let the keeper's Python use the microphone: click Allow.
+- Install waits up to 60 s for the keeper to hear something. If it does not,
+  one line names System Settings > Privacy & Security > Microphone and the
+  app, and install exits 2
+  ([troubleshooting](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/troubleshooting.md#install-the-microphone-was-not-heard)).
+- A re-install with listening already on runs the same check.
+  `EARS_MIC_CHECK_S=0` turns it off.
 
 ### The proof of a working install: you speak, and the agent WAKES and answers
 
@@ -343,7 +390,8 @@ it pages nobody: the agent is woken by the turn MAIL (`mail`,
 An install that stops at "the user speaks, a heard line appears" can leave the
 agent deaf to its person, and one that retires room mode on that proof goes
 deaf for good. So the proof is: say "hey NAME", and NAME wakes and
-answers.
+answers. Install's `mic    heard:` line proves the keeper hears, not that
+anyone wakes: when the mic is NOT heard, install leaves out its proof line.
 
 `ears services install` (`--dry-run` lists the same checks and writes nothing).
 Before it writes anything, it checks every prerequisite it can check without
@@ -353,10 +401,10 @@ also makes it exit 2, once every other service has been tried: one block on
 stderr names each service that did not load, the install log and `ears
 services status`. Every real run appends its output and launchctl's answers,
 timestamped, to `install.log` in the log folder, `~/.sessionkit/voice/log/`, and prints that path
-as its `log` row ([logs](docs/logs.md#the-log-files)). It then:
+as its `log` row ([logs](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/logs.md#the-log-files)). It then:
 
 - first finds the mlx-audio speech server on `:8890`, or installs its own
-  (`dev.sessionkit.voice.mlx-audio`), as [the speech server](docs/speech-server.md)
+  (`dev.sessionkit.voice.mlx-audio`), as [the speech server](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/speech-server.md)
   page says, and prints which step it took. When it loads its own, the new
   `final` below is written without the probe: that server has not started
   yet;
@@ -395,11 +443,12 @@ as its `log` row ([logs](docs/logs.md#the-log-files)). It then:
   postfix and makes the `heard` box with `message setup --box heard`
   (which also makes sessionmail's mail root, your own box and its notmuch
   profile, if they are missing, and prints each one). On a host that
-  sends by postfix, it makes the `heard` box NESTED under the store dir
-  that carries `.tm-store`, as `~/.mail/agents/<store>/heard/`, when there
-  is exactly one such dir, then runs `vmailbox-gen` if that is on `PATH`,
-  and otherwise prints the commands (`~/.mail/.postfix/vmailbox-gen`:
-  sessionmail keeps it off `PATH`). When sessionmail's answer cannot be
+  sends by postfix, it makes the `heard` box NESTED under the store box
+  (`message box list` names it; `message path <store>` is its folder), as
+  `<store>/heard/`, when there is exactly one, then runs this host's
+  `vmailbox-gen` as sessionmail names it (`message path --generator`), and
+  otherwise prints the commands. sessionvoice never spells the mail root:
+  every box is sessionmail's answer. When sessionmail's answer cannot be
   read (no `message`, or one older than 0.2.0), it warns, makes no box,
   checks neither, and goes on.
   On a postfix host it also prints the box to subscribe to:
@@ -413,7 +462,9 @@ as its `log` row ([logs](docs/logs.md#the-log-files)). It then:
   `ears services install --agent NAME` for a Mac where an agent seat should
   be woken when you speak, and `ears services install --no-agent` for a
   phone-only Mac (for example a Delta bot), where nobody is woken and the
-  notices go to the log; then `ears wake add NAME`, to add a seat later. Inside
+  notices go to the log; then `ears wake add NAME`, to add a seat later, or
+  `ears wake add --self` in the seat's agent file, to register it at every
+  launch ([docs/ears.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/ears.md#wake-seats)). Inside
   an agent seat (`TM_AGENT_ADDRESS` set) it suggests that address's local
   part as NAME; it never installs on the suggestion. `--no-agent` installs
   anyway, and install warns that NOBODY is woken. A wake file that already
@@ -443,7 +494,14 @@ as its `log` row ([logs](docs/logs.md#the-log-files)). It then:
   STT models: this project's own extra pins `mlx-audio>=0.5.4`. An mlx-audio
   that answers every Parakeet request 500 (`No module named
   mlx_audio.tts.models.parakeet_tdt_0`) is not one, and the probe catches it.
-  That the cause is an older mlx-audio is an inference, not measured.
+  That the cause is an older mlx-audio is an inference, not measured;
+- with listening on (`--listen`, or already on), after the last service loads
+  and before the speech weights download, waits up to 60 s
+  (`EARS_MIC_CHECK_S`) for the keeper's first heartbeat with sound. Heard: one
+  `mic` row. Not heard: one line on stderr naming the Privacy setting and the
+  app, and exit 2. Every case it cannot check (listening off, no microphone,
+  a live call, a hand-made keeper, `EARS_MIC_CHECK_S=0`) gets one
+  `mic    not checked:` row instead, with the exit unchanged.
 
 **The ride-along hook is a step of its own.** Installing the Claude Code
 plugin does not turn it on: the plugin ships no hooks, so no agent sees what
@@ -474,7 +532,7 @@ shows only the partial preview of a turn still being spoken and the shown
 events (wake word, barge-in, device change), never the finished turn a
 second time. `EARS_HEARD_PARTIALS_ONLY=1`, or `"heard_partials_only": true`
 in `ears.json`, does the same without editing the command
-([docs/ears.md](docs/ears.md#the-heard-hook)). `ears heard hook --help`
+([docs/ears.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/ears.md#the-heard-hook)). `ears heard hook --help`
 prints its usage.
 
 ## Tests

{sessionvoice-0.3.2 → sessionvoice-0.4.0}/README.md

@@ -28,7 +28,7 @@ streams transcription, and decides when the speaker has finished.
   for a while.
 - **Barge-in:** on headphones or a call, talk over the assistant and its voice
   dips at once; a couple of your own words, or "stop", cut it off
-  ([barge-in](docs/barge-in.md)).
+  ([barge-in](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/barge-in.md)).
 
 ## Requirements
 
@@ -38,19 +38,21 @@ streams transcription, and decides when the speaker has finished.
 - [ ] Windows
 
 What sessionvoice depends on, what needs each one, and how to upgrade it:
-[dependencies](docs/dependencies.md).
+[dependencies](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/dependencies.md).
 
 ## Components
 
 The engine above is the core. Around it, these parts make it an always-on
-pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
+pair of ears on a Mac (depth in [docs/architecture.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/architecture.md)):
 
 - **Capture** (`src/ears/listen`): `ears.listen capture` reads one input
   device and writes every partial, turn and heartbeat to the **heard log**
   (`src/ears/heard.py`):
-  `<home>/logs/conversations/heard_YYYY-MM-DD.jsonl`, where `<home>` is
-  `~/.voicemode` on a host that already keeps it there, else
-  `~/.sessionvoice` ([docs/logs.md](docs/logs.md#sessionvoices-home)).
+  `<root>/logs/conversations/heard_YYYY-MM-DD.jsonl`, where `<root>` is the
+  state root: `~/.sessionkit/voice/state` on a new host, or the old
+  `~/.sessionvoice` or `~/.voicemode` on a host that already keeps its heard
+  log there ([docs/logs.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/logs.md#the-state-root)).
+  `ears home state-dir` prints it.
   On a fresh host that also runs VoiceMode's `converse` as a heard guest,
   set `SESSIONVOICE_HOME=~/.voicemode` (or `VOICEMODE_BASE_DIR`), so that
   both write one log.
@@ -84,9 +86,11 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
 - **Sounds** (`keeper/ears-sounds.py`, launchd `dev.sessionkit.voice.ears-sounds`):
   a short sound in the user's ears when the ears log an event, so they know
   they were heard. Its partner, `keeper/mouth-sounds.py`
-  (`dev.sessionkit.voice.mouth-sounds`), plays the mouth's cues. Opt-in:
-  `ears services install --only sounds` loads both, from an installed
-  package or a checkout; a bare install never does.
+  (`dev.sessionkit.voice.mouth-sounds`), plays the mouth's cues. A bare
+  `ears services install` loads both, from an installed package or a
+  checkout. From the first turn the ears' turn and partial ticks are on
+  (Settings turns them off), and so are the mouth's five cues
+  (`mouth-sounds.json` in the settings folder turns each off).
 - **Turn mail** (`keeper/ears-mail.py`, launchd `dev.sessionkit.voice.ears-mail`):
   mails each of the user's finished turns To and From
   `heard+room@<host>`, whatever input device the capture is following, with
@@ -115,6 +119,12 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
   label is dropped: the remaining words get `--speaker` (else
   `unknown@<host>`), never the seat whose echo was cut, and they can be a
   reply to that seat. A label naming anyone else is kept.
+  `Ears-Addressed` lists the seats a turn names, as `<seat>@<host>`, wherever
+  the name falls in the turn, plus `everyone` for "hey everyone":
+  `Ears-Addressed: everyone, ivy@<host>`. A seat is named by its `names` in
+  the wake file. The header carries names only, never the turn's words, and a
+  turn that names nobody has no `Ears-Addressed`. It goes on the room mail
+  only. [docs/ears.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/ears.md) gives the rules.
   `Ears-Echo` says a mouth line heard back through the mic was cut out of
   the turn. On the speakers the mic hears the mouth, so a line's
   words are cut wherever they sit in the user's turn: at its start (up to `3 + 5
@@ -143,6 +153,25 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
   have opened within 2 s of the line beginning, unless the turn is mostly
   the line. On the `ts − (t1 − t0)` estimate, only the first two guards
   apply. Numerals (`9%` for "nine percent") still slip past the word match.
+  `Ears-Said` names each session's own line the turn came after, so the
+  pager can keep that session's window open (its linger):
+  `Ears-Said: <session>@<host>=<end>, ...`. `<session>` is the full session
+  id on the line's `said` row, `<host>` the keeper's, and `<end>` that
+  row's `ts`, as it was written. Each session gets one entry: its newest line
+  that finished at or before the turn's `Ears-Start`, within 600 s. It
+  carries spoken lines only: a line on `lane: file` (a music bed or a sound
+  file) is left out, so a bed that ends after a line leaves that line the
+  session's newest. A line with `interest: zero`, or one cut before it
+  played a word (`played_s` 0), is left out. A line the user barged into after part of it played counts,
+  at its cut. Entries are sorted, and the header holds names and times,
+  never a line's words. It goes on the device mail and the `--to seats`
+  mail, never on a cut notice or a call turn; with no entry there is no
+  header.
+  `Ears-Film: playing` marks a turn the keeper heard while a film was
+  playing (`--kodi`: the state that holds `reply` and `light`), so the
+  pager can tell film dialogue from the user. It is a fact about the turn,
+  with one value, on the device mail only; with no film playing, or no
+  `--kodi`, there is no header. Kodi is asked at most once per turn.
 - **Waiter** (`bin/heard-first`): an agent blocks on the heard log
   until a line is for it, by `--rule`: its name in a partial or a
   turn (`partial:REGEX`, `turn:REGEX`), a reply to its last line
@@ -169,7 +198,7 @@ pair of ears on a Mac (depth in [docs/architecture.md](docs/architecture.md)):
 - **Speaker names** (`speakers/`, opt-in:
   `ears services install --only speakers`): a side-car tags each heard line
   with who spoke, in `speakers_YYYY-MM-DD.jsonl` beside the heard log, and
-  the waiters read it. See [speakers/README.md](speakers/README.md).
+  the waiters read it. See [speakers/README.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/speakers/README.md).
 
 ## Configuration
 
@@ -185,21 +214,22 @@ Three JSON settings files, each reread with no restart:
   read only their own file.
 
 Environment variables win over single keys (`EARS_RECORD` over `record`,
-`MOUTH_DEVICE` over `output`). `SESSIONVOICE_HOME` moves the home that holds
-the heard log and each part's state; by default it is `~/.sessionvoice`, or
-`~/.voicemode` on a host that already keeps its heard log there. The launch
-agents are in `~/Library/LaunchAgents/`.
+`MOUTH_DEVICE` over `output`). `SESSIONVOICE_HOME` moves the state root,
+which holds the heard log and each part's state; by default it is
+`~/.sessionkit/voice/state`, or the old `~/.sessionvoice` or `~/.voicemode` on
+a host that already keeps its heard log there. The launch agents are in
+`~/Library/LaunchAgents/`.
 
 Which files and which variables each part reads, and where each one lives:
-[docs/configuration.md](docs/configuration.md).
+[docs/configuration.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/configuration.md).
 Every key, its type and its default:
-[docs/settings.md](docs/settings.md).
+[docs/settings.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/settings.md).
 
 ## Logs
 
-- **The heard log:** `<home>/logs/conversations/heard_YYYY-MM-DD.jsonl`,
+- **The heard log:** `<root>/logs/conversations/heard_YYYY-MM-DD.jsonl`,
   one JSON line for each thing the ears heard and the mouth said, where
-  `<home>` is the home above. A new file starts each day.
+  `<root>` is the state root above (`ears home state-dir` prints it). A new file starts each day.
 - **The services' logs:** `~/.sessionkit/voice/log/` (`EARS_LOG_DIR` moves it).
   `ears-keeper.log` is what the keeper did (devices, restarts, calls, a
   deaf mic); `ears-keeper-capture.log` is the room capture's own output;
@@ -209,9 +239,9 @@ Every key, its type and its default:
 
 Follow one with `tail -F`, for example
 `tail -F ~/.sessionkit/voice/log/ears-keeper.log`, or today's heard log with
-`tail -F <home>/logs/conversations/heard_$(date +%F).jsonl`.
+`tail -F "$(ears home state-dir)/logs/conversations/heard_$(date +%F).jsonl"`.
 Every log file and what each line means:
-[docs/logs.md](docs/logs.md).
+[docs/logs.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/logs.md).
 
 - **Health:** `ears services status` prints one row per launch agent
   (`running, pid N`, `loaded, not running` or `not installed`; the
@@ -258,12 +288,13 @@ conversation either. On the host, run `talk pair` in a terminal and open the
 link it prints; `talk token --rotate` makes every browser pair again. Open talk
 at `http://127.0.0.1:<port>/`, never at `localhost`. The code is `src/talk/`.
 `ears services install --only talk` keeps it running as a launch agent
-(opt-in; a bare install never does).
+(opt-in; a bare install never does); add `--allow-host
+machine.example.ts.net` for a phone behind `tailscale serve`.
 
 In the kit's web page, Talk is a room: the kit's front door runs
 `talk serve --kit` on a unix socket and logs you in, so there is nothing to
 pair and you never run `--kit` by hand
-([docs/talk.md](docs/talk.md#in-the-kits-web-page)).
+([docs/talk.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/talk.md#in-the-kits-web-page)).
 
 ## Install
 
@@ -277,8 +308,7 @@ import that needs one fails naming it, as `pip install 'sessionvoice[EXTRA]'`.
 
     uv venv && uv pip install -e '.[all]'  # onnxruntime + mlx-audio
     ears install
-    ears services install --agent NAME     # the launch agents: mouth, keeper, mail
-    ears services install --only sounds    # opt-in: the ears and mouth sounds
+    ears services install --agent NAME     # the launch agents: mouth, keeper, mail, sounds
     ears services install --only talk      # opt-in: talk serve, the live view
 
 A phone-only Mac (for example one that runs a Delta bot, with no agent
@@ -288,7 +318,24 @@ an agent seat should be woken when you speak. Before it writes anything,
 install says how big the speech models are (about 2.9 GB, fetched once,
 after the speech server loads) and that the speech server runs as a login
 service; `--dry-run` prints the same line, and `--no-prefetch` leaves the
-download to the first call.
+download to the first call. `--no-prefetch` does not cover the Silero VAD
+model (2.3 MB): install still fetches a missing one, because the keeper
+cannot hear without it.
+
+A fresh install leaves the room's ear off. To turn it on now, and check the
+microphone while you are at the Mac:
+
+    ears services install --agent NAME --listen
+
+- Typing `--listen` is the consent: it writes `"listen": true` to `ears.json`
+  before the keeper loads.
+- macOS asks to let the keeper's Python use the microphone: click Allow.
+- Install waits up to 60 s for the keeper to hear something. If it does not,
+  one line names System Settings > Privacy & Security > Microphone and the
+  app, and install exits 2
+  ([troubleshooting](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/troubleshooting.md#install-the-microphone-was-not-heard)).
+- A re-install with listening already on runs the same check.
+  `EARS_MIC_CHECK_S=0` turns it off.
 
 ### The proof of a working install: you speak, and the agent WAKES and answers
 
@@ -299,7 +346,8 @@ it pages nobody: the agent is woken by the turn MAIL (`mail`,
 An install that stops at "the user speaks, a heard line appears" can leave the
 agent deaf to its person, and one that retires room mode on that proof goes
 deaf for good. So the proof is: say "hey NAME", and NAME wakes and
-answers.
+answers. Install's `mic    heard:` line proves the keeper hears, not that
+anyone wakes: when the mic is NOT heard, install leaves out its proof line.
 
 `ears services install` (`--dry-run` lists the same checks and writes nothing).
 Before it writes anything, it checks every prerequisite it can check without
@@ -309,10 +357,10 @@ also makes it exit 2, once every other service has been tried: one block on
 stderr names each service that did not load, the install log and `ears
 services status`. Every real run appends its output and launchctl's answers,
 timestamped, to `install.log` in the log folder, `~/.sessionkit/voice/log/`, and prints that path
-as its `log` row ([logs](docs/logs.md#the-log-files)). It then:
+as its `log` row ([logs](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/logs.md#the-log-files)). It then:
 
 - first finds the mlx-audio speech server on `:8890`, or installs its own
-  (`dev.sessionkit.voice.mlx-audio`), as [the speech server](docs/speech-server.md)
+  (`dev.sessionkit.voice.mlx-audio`), as [the speech server](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/speech-server.md)
   page says, and prints which step it took. When it loads its own, the new
   `final` below is written without the probe: that server has not started
   yet;
@@ -351,11 +399,12 @@ as its `log` row ([logs](docs/logs.md#the-log-files)). It then:
   postfix and makes the `heard` box with `message setup --box heard`
   (which also makes sessionmail's mail root, your own box and its notmuch
   profile, if they are missing, and prints each one). On a host that
-  sends by postfix, it makes the `heard` box NESTED under the store dir
-  that carries `.tm-store`, as `~/.mail/agents/<store>/heard/`, when there
-  is exactly one such dir, then runs `vmailbox-gen` if that is on `PATH`,
-  and otherwise prints the commands (`~/.mail/.postfix/vmailbox-gen`:
-  sessionmail keeps it off `PATH`). When sessionmail's answer cannot be
+  sends by postfix, it makes the `heard` box NESTED under the store box
+  (`message box list` names it; `message path <store>` is its folder), as
+  `<store>/heard/`, when there is exactly one, then runs this host's
+  `vmailbox-gen` as sessionmail names it (`message path --generator`), and
+  otherwise prints the commands. sessionvoice never spells the mail root:
+  every box is sessionmail's answer. When sessionmail's answer cannot be
   read (no `message`, or one older than 0.2.0), it warns, makes no box,
   checks neither, and goes on.
   On a postfix host it also prints the box to subscribe to:
@@ -369,7 +418,9 @@ as its `log` row ([logs](docs/logs.md#the-log-files)). It then:
   `ears services install --agent NAME` for a Mac where an agent seat should
   be woken when you speak, and `ears services install --no-agent` for a
   phone-only Mac (for example a Delta bot), where nobody is woken and the
-  notices go to the log; then `ears wake add NAME`, to add a seat later. Inside
+  notices go to the log; then `ears wake add NAME`, to add a seat later, or
+  `ears wake add --self` in the seat's agent file, to register it at every
+  launch ([docs/ears.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/ears.md#wake-seats)). Inside
   an agent seat (`TM_AGENT_ADDRESS` set) it suggests that address's local
   part as NAME; it never installs on the suggestion. `--no-agent` installs
   anyway, and install warns that NOBODY is woken. A wake file that already
@@ -399,7 +450,14 @@ as its `log` row ([logs](docs/logs.md#the-log-files)). It then:
   STT models: this project's own extra pins `mlx-audio>=0.5.4`. An mlx-audio
   that answers every Parakeet request 500 (`No module named
   mlx_audio.tts.models.parakeet_tdt_0`) is not one, and the probe catches it.
-  That the cause is an older mlx-audio is an inference, not measured.
+  That the cause is an older mlx-audio is an inference, not measured;
+- with listening on (`--listen`, or already on), after the last service loads
+  and before the speech weights download, waits up to 60 s
+  (`EARS_MIC_CHECK_S`) for the keeper's first heartbeat with sound. Heard: one
+  `mic` row. Not heard: one line on stderr naming the Privacy setting and the
+  app, and exit 2. Every case it cannot check (listening off, no microphone,
+  a live call, a hand-made keeper, `EARS_MIC_CHECK_S=0`) gets one
+  `mic    not checked:` row instead, with the exit unchanged.
 
 **The ride-along hook is a step of its own.** Installing the Claude Code
 plugin does not turn it on: the plugin ships no hooks, so no agent sees what
@@ -430,7 +488,7 @@ shows only the partial preview of a turn still being spoken and the shown
 events (wake word, barge-in, device change), never the finished turn a
 second time. `EARS_HEARD_PARTIALS_ONLY=1`, or `"heard_partials_only": true`
 in `ears.json`, does the same without editing the command
-([docs/ears.md](docs/ears.md#the-heard-hook)). `ears heard hook --help`
+([docs/ears.md](https://github.com/sessionkit/sessionvoice/blob/HEAD/docs/ears.md#the-heard-hook)). `ears heard hook --help`
 prints its usage.
 
 ## Tests

{sessionvoice-0.3.2 → sessionvoice-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sessionvoice"
-version = "0.3.2"
+version = "0.4.0"
 description = "One listening engine for coding agents and the Delta bot: Apple / Nemotron / whisper -> one event stream -> VAD -> turns"
 readme = "README.md"
 license = "AGPL-3.0-or-later"
@@ -89,8 +89,9 @@ ears = ["_keeper/ears-keeper.sh", "_keeper/call-ears", "_keeper/input-watch.swif
 # same way. They are data, never imported by the mouth: `mouth split` runs run.py in the
 # separator venv. torch and demucs, that venv's, are in no dependency list here.
 mouth = ["_separator/*"]
-# talk serves its page and manifest from beside server.py
-talk = ["index.html", "manifest.json"]
+# talk serves its page, manifest and icons from beside server.py
+talk = ["index.html", "manifest.json", "icon.svg", "favicon.ico", "apple-touch-icon.png",
+        "icon-192.png", "icon-512.png", "icon-mask-512.png"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{sessionvoice-0.3.2 → sessionvoice-0.4.0}/src/ears/_keeper/call-ears

@@ -12,8 +12,8 @@ A call already live when this starts keeps the ear it has (one restarted with th
 leaves its captures running), and one with no ear gets one. Once, every already-live
 call was left alone, so a restart mid-call left that call deaf to the end.
 Stop: touch $CALL_EARS_DIR/STOP. Log: stdout (the keeper's $EARS_LOG_DIR/ears-keeper-calls.log);
-each ear's in $CALL_EARS_DIR/capture-N.log. CALL_EARS_DIR defaults to
-${XDG_STATE_HOME:-~/.local/state}/ears/call-ears (it was ~/.<agent>/call-ears).
+each ear's in $CALL_EARS_DIR/capture-N.log. CALL_EARS_DIR defaults to the state item
+call-ears (`ears home state-dir call-ears`; it was ~/.<agent>/call-ears, then an XDG folder).
 
 The room and the calls were once two launch agents; now they are one, so
 this is not a launch
@@ -30,9 +30,42 @@ if os.path.dirname(os.path.abspath(__file__)) not in sys.path:
 import phone_roots  # noqa: E402  (keeper/ is not a package)
 
 HOME = Path.home()
-# The keeper passes its own; the default is the keeper's (keeper/ears-keeper.sh), change both.
-DIR = Path(os.environ.get("CALL_EARS_DIR")
-           or Path(os.environ.get("XDG_STATE_HOME") or HOME / ".local/state") / "ears/call-ears")
+HERE = Path(__file__).resolve().parent
+
+
+def voice_home():
+    """ears/home.py, the ONE place voice names its state items.
+    keeper/ imports nothing from the ears package, so it loads home.py (standard library
+    only) by its path, once: the checkout's src/ears/home.py, else the wheel's ears/home.py
+    above ears/_keeper/. Not there: exit 2, naming where it looked; there is no copy of the
+    rule to fall back on."""
+    mod = getattr(voice_home, "mod", None)
+    if mod is None:
+        import importlib.util
+        tried = [HERE.parent / "src/ears/home.py", HERE.parent / "home.py"]
+        f = next((f for f in tried if f.is_file()), None)
+        if f is None:
+            print(f"call-ears: no ears/home.py at {' nor '.join(map(str, tried))}: it names "
+                  "voice's state folders. Run it from a sessionvoice checkout, the plugin or the "
+                  "package, or set CALL_EARS_DIR", file=sys.stderr)
+            sys.exit(2)
+        spec = importlib.util.spec_from_file_location("_voice_home", f)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        voice_home.mod = mod
+    return mod
+
+
+def voice_state_path(item: str) -> Path:
+    """The state item ITEM's path, as the PACKAGE answers it (ears.home.asked_state_path):
+    its own variable wins and asks nothing; else exit 2, naming both answers, when the package
+    cannot be asked or disagrees with this checkout's home.py."""
+    return voice_home().asked_state_path(item, "call-ears")
+
+
+# The keeper passes its own (CALL_EARS_DIR, always): this default is for a run by hand, and it
+# is the keeper's, the state item call-ears (ears-keeper.sh asks the same).
+DIR = voice_state_path("call-ears")
 STOP = DIR / "STOP"
 # The calls the probe finds live, "call:N,call:M", rewritten every loop (so its age says this
 # is alive): the keeper's room-off rule reads it. A capture is no proof of a live call - one