vocalize-cli 0.10.0__tar.gz → 0.10.1__tar.gz

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/CHANGELOG.md

@@ -3,6 +3,42 @@
 All notable changes to this project are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.10.1 - 2026-09-02
+
+Three fixes found in the first owner-present run of 0.10.0's dictation.
+Together they meant no hotkey dictation could succeed on 0.10.0; upgrade.
+
+### Fixed
+
+- **No dictation could ever start on a fresh install.** The recorder was
+  signed with the hardened runtime but without the
+  `com.apple.security.device.audio-input` entitlement, so macOS refused the
+  microphone on the spot — no permission dialog, status stuck at
+  `notDetermined` — and every first press ended in "The recorder did not
+  start". The bundle is now signed with
+  `vocalize/recorder/Recorder.entitlements`, and the entitlements are part
+  of the recorder's fingerprint, so `vocalize local install --stt` rebuilds
+  the bundle once (and, as with any rebuild, macOS asks for the microphone
+  again — it never actually asked before).
+- **Every hotkey dictation ended in "Dictation failed" on a machine whose
+  `uv` came from Homebrew.** A Services environment has a bare PATH, and
+  `uv_path()` looked only there and in `~/.local/bin`; the same dictation
+  worked from a terminal. `/opt/homebrew/bin/uv` and `/usr/local/bin/uv`
+  are now tried too (this also covers Kokoro from a Quick Action).
+- **Holding the dictation hotkey down turned into a cancel-and-restart
+  loop.** macOS re-fires a Service shortcut at the key-repeat rate, and
+  every repeat landed as a second press. Presses within half a second of
+  the previous one are now ignored as the same press; a deliberate cancel
+  is "press, a beat, press" inside the two-second window, as before.
+- `hooks/claude_stop_hook.py --latest`, run from inside a Claude Code turn
+  (which is how `/speak` runs it), spoke the agent's own status line —
+  "Checking settings." — instead of the response the user asked to hear.
+  It now skips the turn in progress, back past the `/speak` message
+  itself, and speaks the response before it. From a plain terminal, where
+  no turn is in progress, `--latest` still speaks the newest response; the
+  hook tells the two apart by the `CLAUDECODE` variable Claude Code sets
+  in its shell. The Stop-hook path is unchanged.
+
 ## 0.10.0 - 2026-09-02
 
 ### Added

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vocalize-cli
-Version: 0.10.0
+Version: 0.10.1
 Summary: A CLI that turns text, markdown, or piped stdin into speech via the ElevenLabs API, with markdown-table-aware preprocessing.
 Project-URL: Homepage, https://github.com/matthager12-collab/vocalize
 Project-URL: Repository, https://github.com/matthager12-collab/vocalize
@@ -478,7 +478,8 @@ terminal, if you'd rather trigger it that way.
   transcript is on your clipboard; nothing is typed for you automatically.
 - **Nothing heard** (silence, or a microphone that isn't actually picking
   anything up) ends the dictation quietly — no clipboard write.
-- **Cancel** with a second press *within two seconds* of the first, or at
+- **Cancel** with a second press *within two seconds* of the first (but
+  not within half a second — that's a held key, and it's ignored), or at
   any point with `vocalize listen --cancel` — the audio is discarded, never
   transcribed.
 - **A third press while transcribing is refused**: a Pop, and "Still

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/README.md

@@ -442,7 +442,8 @@ terminal, if you'd rather trigger it that way.
   transcript is on your clipboard; nothing is typed for you automatically.
 - **Nothing heard** (silence, or a microphone that isn't actually picking
   anything up) ends the dictation quietly — no clipboard write.
-- **Cancel** with a second press *within two seconds* of the first, or at
+- **Cancel** with a second press *within two seconds* of the first (but
+  not within half a second — that's a held key, and it's ignored), or at
   any point with `vocalize listen --cancel` — the audio is discarded, never
   transcribed.
 - **A third press while transcribing is refused**: a Pop, and "Still

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/docs/dictation.md

@@ -132,7 +132,10 @@ touching System Settings at all.
 
 **A second press within two seconds of the first is a cancel**, not a
 stop — treated as "I changed my mind" rather than the end of a very short
-sentence. So is `vocalize listen --cancel`, from a terminal, at any point
+sentence. (Presses closer than half a second apart are the key being
+*held* — macOS repeats a Service shortcut at the key-repeat rate — and are
+ignored, so a cancel is "press, a beat, press".) So is
+`vocalize listen --cancel`, from a terminal, at any point
 — including while a take is being transcribed. (The transcription that was
 already running keeps its own copy of the recording and finishes normally;
 `--cancel` only releases the hotkey so your next press starts a fresh

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/docs/plans/2026-09-next-features/run-6-release-0-10-0/report.md

@@ -11,6 +11,7 @@ Branch `next-features`, shared checkout. Source: [project-plan.md](./project-pla
   - `status` (no mic): [run-1-status/report.md](../run-1-status/report.md) (the module and its exit-code contract) plus [run-4-dictation/report.md](../run-4-dictation/report.md) T-45 (the four STT readiness rows), further hardened this run (mic-verdict age, locked probe registry — see review-0.10.0.md).
   - Resume drill (no mic): [run-5-resume/report.md](../run-5-resume/report.md) T-46/T-47, with this run's review closing the gaps it left open (DEC-013's queued-read case, DEC-014f's voice/speed/chunking carry-over).
   - Note: rebuilding the recorder for the Swift permission-dialog fix (`94e5a46`) reset the microphone grant on the reference Mac to `notDetermined`, so Manual check 1 starts from a genuinely fresh state — not a regression, the state the fix exists for.
+  - **Owner-present run, 2026-09-02 evening (after 0.10.0 published):** Manual check 1 (mic grant) and 2 (hotkey path, real voice, transcript on the clipboard) done — but only after three defects were fixed and released as 0.10.1: the recorder was signed with the hardened runtime and no `audio-input` entitlement (no prompt ever appeared); `uv_path()` could not find Homebrew's uv from a Service's bare PATH (every stop ended in "Dictation failed"); and a held hotkey re-fired as serial cancel/restart presses (now debounced). Manual 3 is partly covered (held-key refusal); 4, 4b, 4c and 5 remain.
 - **T-53: pending** — merge and publish. Not started. This run does not merge to main or publish; per project-plan.md that happens on the owner's word, after T-52. The orchestrator handles this after reading this report.
 
 ## Security-gate summary (every run's verdict)

vocalize_cli-0.10.1/docs/roadmap.md

@@ -0,0 +1,24 @@
+# Roadmap
+
+Future work, with the research behind each item. Status legend: **planned** = analysed, decisions pending, nothing built; **spiked** = feasibility measured; **building**; **shipped**.
+
+| Item | Status | Tracking | Research |
+|---|---|---|---|
+| Hotkey-triggered local dictation (voice → text via a local Whisper model, Quick Action toggle, clipboard output, optional cleanup) | **shipped** in 0.10.0, usable from 0.10.1 | [#1](https://github.com/matthager12-collab/vocalize/issues/1) · [plan](plans/2026-09-next-features/plan.md) | [analysis](next-features-analysis.md) · [full design](research/2026-09-01-dictation-design.md) · [voicebox findings](research/2026-09-01-voicebox-findings.md) |
+| `vocalize status` one-screen readiness check | **shipped** in 0.10.0 | [#1](https://github.com/matthager12-collab/vocalize/issues/1) | [analysis](next-features-analysis.md) |
+| Spoken cues for dictation (`[stt] cues = "words"`: "start" / "stopped" / "ready" instead of, or as well as, the sounds) | building | — | owner request, 2026-09-02 |
+| Config portal (`vocalize portal`, stdlib local web page on top of the same readiness rows) | planned — runs 7–10 of the [plan](plans/2026-09-next-features/plan.md) | [#1](https://github.com/matthager12-collab/vocalize/issues/1) | [analysis](next-features-analysis.md) · [full design](research/2026-09-01-config-portal-design.md) |
+
+## Decisions (2026-09-01, closed 2026-09-02)
+
+1. The dictation spike ran ([results](plans/2026-09-next-features/spike-2026-09-01.md)); Whisper `small.en` is the default.
+2. `vocalize status` first (0.10.0); the portal follows as 0.11.0.
+3. Hotkey chord ⌃⌥⌘D, set by the user in System Settings.
+
+## Deferred on purpose
+
+Hold-to-talk (needs an event tap + Input Monitoring, ~6 h), auto-paste (Accessibility, ~2 h, belongs in the recorder bundle), Apple STT mode (~1.5 h), menu-bar agent (~12 h), local-LLM cleanup, resident/pre-warmed STT worker (only if the spike shows >2.5 s overhead), a native SwiftUI/Tauri app.
+
+## Sequencing suggestion
+
+Dictation first (the spike decides the engine, then ~20 h), portal or `status` second.

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/hooks/claude_stop_hook.py

@@ -7,7 +7,10 @@
 2. On demand, with `--latest`. Nothing is read from stdin; the script finds
    the most recently written transcript under ~/.claude/projects and speaks
    that response. Run it when you want speech instead of installing the
-   hook and getting it after every turn.
+   hook and getting it after every turn. Run from inside a Claude Code turn
+   (the /speak command does this; Claude Code sets CLAUDECODE=1 in its
+   shell) it skips that turn — the newest text there is the agent's own
+   status line — and speaks the response before it.
 
 Add `--print-length` to either mode to print the response's character
 count instead of speaking — for wrappers deciding whether to ask about
@@ -59,7 +62,27 @@ def _speech_timeout(text: str) -> int:
     return min(TIMEOUT_CEILING_SECONDS, TIMEOUT_BASE_SECONDS + len(text) // CHARS_PER_SECOND)
 
 
-def _extract_last_assistant_text(transcript_path: str) -> str:
+def _is_human_message(entry: dict) -> bool:
+    """A user entry the person typed, not one Claude Code wrote.
+
+    Claude Code logs tool results and its own injected text — a skill's
+    body, say — as user entries too; the latter carry ``isMeta``.
+    """
+    if entry.get("type") != "user" or entry.get("isMeta"):
+        return False
+    content = (entry.get("message") or {}).get("content") or []
+    if isinstance(content, str):
+        return True
+    return any(isinstance(b, dict) and b.get("type") != "tool_result" for b in content)
+
+
+def _extract_last_assistant_text(transcript_path: str, skip_current_turn: bool = False) -> str:
+    """Newest assistant text in the transcript.
+
+    With skip_current_turn, everything after the newest human message is
+    the turn still in progress (the one running this script); skip it and
+    return the response before that message instead.
+    """
     last_text_parts: list[str] = []
     try:
         with open(transcript_path, "r", encoding="utf-8") as f:
@@ -76,6 +99,11 @@ def _extract_last_assistant_text(transcript_path: str) -> str:
         except json.JSONDecodeError:
             continue
 
+        if skip_current_turn:
+            if _is_human_message(entry):
+                skip_current_turn = False  # past the /speak message; older is fair game
+            continue
+
         if entry.get("type") != "assistant":
             continue
 
@@ -117,17 +145,24 @@ def main() -> int:
     if "--latest" in sys.argv[1:]:
         # On-demand mode: no hook payload on stdin, so don't read it at all.
         transcript_path = _find_latest_transcript()
+        # Run from inside a Claude Code turn (the /speak command does this,
+        # and Claude Code sets CLAUDECODE=1 in its shell), the newest
+        # assistant text is that turn's own status line — "Checking
+        # settings." — not the response the user asked to hear. From a plain
+        # terminal there is no turn in progress and the newest text is right.
+        skip_current_turn = bool(os.environ.get("CLAUDECODE"))
     else:
         try:
             payload = json.load(sys.stdin)
         except json.JSONDecodeError:
             payload = {}
         transcript_path = payload.get("transcript_path")
+        skip_current_turn = False  # at Stop the turn is over: newest text is the target
 
     if not transcript_path:
         return 0  # nothing to do — don't block Claude Code on a hook error
 
-    text = _extract_last_assistant_text(transcript_path)
+    text = _extract_last_assistant_text(transcript_path, skip_current_turn)
     if not text.strip():
         if "--print-length" in sys.argv[1:]:
             print(0)

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/tests/test_claude_stop_hook.py

@@ -14,6 +14,10 @@ def _assistant(content) -> str:
     return json.dumps({"type": "assistant", "message": {"content": content}})
 
 
+def _user(content, **extra) -> str:
+    return json.dumps({"type": "user", "message": {"content": content}, **extra})
+
+
 def _text(text: str) -> dict:
     return {"type": "text", "text": text}
 
@@ -28,6 +32,9 @@ def _patch_main(monkeypatch, payload, which="/usr/local/bin/vocalize", run=None,
     """Wire up stdin, PATH lookup and subprocess so main() can't shell out."""
     monkeypatch.delenv("VOCALIZE_MAX_CHARS", raising=False)
     monkeypatch.delenv("VOCALIZE_BIN", raising=False)
+    # The suite itself often runs inside a Claude Code turn, where this is
+    # set; a --latest test must not change meaning depending on who ran it.
+    monkeypatch.delenv("CLAUDECODE", raising=False)
     monkeypatch.setattr(hook.sys, "argv", ["claude_stop_hook.py"])
     monkeypatch.setattr(
         hook.sys, "stdin", io.StringIO(json.dumps(payload)) if stdin is None else stdin
@@ -102,6 +109,31 @@ def test_falls_back_past_tool_use_only_entry(tmp_path):
     assert hook._extract_last_assistant_text(path) == "the spoken answer"
 
 
+def test_skip_current_turn_returns_the_response_before_the_newest_human_message(tmp_path):
+    # /speak runs the hook mid-turn. By then the agent has written a status
+    # line and Claude Code has logged the Bash call that runs the hook (and
+    # its result). The response the user wants is the one BEFORE /speak.
+    # Only the typed /speak line counts as the person speaking: tool results
+    # and Claude Code's own injected text (isMeta) are user entries too.
+    path = _write_transcript(
+        tmp_path,
+        [
+            _assistant([_text("the long response the user asked to hear")]),
+            _user("<command-name>/speak</command-name>"),
+            _user([_text("Base directory for this skill: ...")], isMeta=True),
+            _assistant([_text("Checking settings.")]),
+            _assistant([{"type": "tool_use", "name": "Bash", "input": {}}]),
+            _user([{"type": "tool_result", "tool_use_id": "t1", "content": "ok"}]),
+        ],
+    )
+
+    assert hook._extract_last_assistant_text(path, skip_current_turn=True) == (
+        "the long response the user asked to hear"
+    )
+    # The Stop-hook path still wants the newest text: at Stop, the turn is over.
+    assert hook._extract_last_assistant_text(path) == "Checking settings."
+
+
 def test_ignores_malformed_json_lines(tmp_path):
     # The garbage line must sit AFTER the newest assistant entry. The scan
     # walks reversed(lines) and breaks on the first text it finds, so a
@@ -326,6 +358,35 @@ def test_latest_mode_speaks_newest_transcript_without_reading_stdin(monkeypatch,
     assert calls[0][-1] == "newest session"
 
 
+def test_latest_mode_skips_the_current_turn_only_inside_claude_code(monkeypatch, tmp_path):
+    transcript = tmp_path / "session.jsonl"
+    transcript.write_text(
+        "\n".join(
+            [
+                _assistant([_text("the long response")]),
+                _user("/speak"),
+                _assistant([_text("Checking settings.")]),
+            ]
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    calls = _patch_main(monkeypatch, {})
+    monkeypatch.setattr(hook.sys, "argv", ["claude_stop_hook.py", "--latest"])
+    monkeypatch.setattr(hook, "_find_latest_transcript", lambda: str(transcript))
+
+    # From a plain terminal there is no turn in progress: newest text wins,
+    # exactly as the README's on-demand mode promises.
+    assert hook.main() == 0
+    assert calls[-1][-1] == "Checking settings."
+
+    # Inside a Claude Code turn, that newest text is the agent's own status
+    # line; the user wants the response before their /speak.
+    monkeypatch.setenv("CLAUDECODE", "1")
+    assert hook.main() == 0
+    assert calls[-1][-1] == "the long response"
+
+
 def test_subprocess_failure_is_logged_not_raised(monkeypatch, tmp_path, capsys):
     def boom(argv):
         raise RuntimeError("no audio device")

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/tests/test_dictate.py

@@ -162,6 +162,9 @@ def harness(tmp_path, monkeypatch):
     # the grace for a record no fake read is going to write. The wait has
     # its own two tests below; these are about the toggle.
     monkeypatch.setattr(dictate, "_RESUME_GRACE", 0.05)
+    # Presses here land microseconds apart, which to the real debounce is
+    # a held key. Its own tests below put the window back.
+    monkeypatch.setattr(dictate, "_DEBOUNCE", 0.0)
 
     # A live PID is our recorder; a dead one is nothing. Replaced because
     # no shebang script can ever be *named* `recorder` to real `ps`.
@@ -486,6 +489,74 @@ def test_a_second_press_within_the_window_cancels(recorder, transcriber, harness
     assert any(dictate._NOTIFY_CANCELLED in line for line in harness.notifications())
 
 
+def test_a_held_key_is_ignored_not_cancelled(recorder, transcriber, harness, monkeypatch):
+    """macOS re-fires a Service shortcut at the key-repeat rate while the
+    chord is held. Seen live 2026-09-02: every repeat landed as a cancel and
+    then a fresh start, dozens of times a minute. Presses inside the
+    debounce are the same press."""
+    recorder()
+    transcriber()
+    monkeypatch.setattr(dictate, "_DEBOUNCE", 0.5)
+    assert start() == 0
+
+    for _ in range(3):  # the key is still down
+        assert dictate.toggle(stt()) == 0
+
+    assert dictate.session_path().is_file()  # still recording
+    assert harness.played == ["Tink.aiff"]  # no Pop, no cancel
+    assert harness.notifications() == []
+    assert lines(harness.uv_argv) == []
+
+
+def test_a_second_tap_after_the_debounce_still_cancels(recorder, transcriber, harness, monkeypatch):
+    recorder()
+    transcriber()
+    monkeypatch.setattr(dictate, "_DEBOUNCE", 0.05)
+    start()
+    time.sleep(0.06)
+
+    assert dictate.toggle(stt()) == 0  # inside the two-second cancel window
+
+    assert not dictate.session_path().exists()
+    assert any(dictate._NOTIFY_CANCELLED in line for line in harness.notifications())
+
+
+def test_a_repeat_queued_behind_a_slow_press_is_still_ignored(recorder, harness, monkeypatch):
+    """The Services runner runs presses one after another: a repeat fired
+    while a press was still launching the recorder begins the instant that
+    press returns. Measured from the press's *start*, it would look like a
+    deliberate second tap; the exit stamp is what catches it."""
+    recorder()
+    monkeypatch.setattr(dictate, "_DEBOUNCE", 0.1)
+    launch = dictate._launch_recorder
+
+    def slow_launch(workdir, stt):
+        time.sleep(0.15)  # longer than the whole debounce window
+        return launch(workdir, stt)
+
+    monkeypatch.setattr(dictate, "_launch_recorder", slow_launch)
+    assert start() == 0
+
+    assert dictate.toggle(stt()) == 0  # the queued repeat
+
+    assert dictate.session_path().is_file()
+    assert harness.played == ["Tink.aiff"]
+
+
+def test_the_press_stamp_is_refreshed_by_ignored_presses(recorder, harness, monkeypatch):
+    """Each repeat re-arms the window, so a key held longer than the window
+    stays ignored until it is released."""
+    recorder()
+    monkeypatch.setattr(dictate, "_DEBOUNCE", 0.1)
+    start()
+    for _ in range(4):
+        time.sleep(0.05)  # each gap is inside the window; the total is not
+        assert dictate.toggle(stt()) == 0
+
+    assert dictate.session_path().is_file()
+    assert harness.played == ["Tink.aiff"]
+
+
 def test_cancel_from_the_command_line_discards_the_recording(
     recorder, transcriber, harness
 ):

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/tests/test_kokoro_provider.py

@@ -177,6 +177,8 @@ def no_uv(monkeypatch, tmp_path):
     monkeypatch.setattr(local.shutil, "which", lambda name: None)
     # Path.home() reads $HOME, so this empties the ~/.local/bin fallback too.
     monkeypatch.setenv("HOME", str(tmp_path / "empty-home"))
+    # ...and the Homebrew spots are real paths on a developer's machine.
+    monkeypatch.setattr(local, "UV_FALLBACKS", ())
 
 
 @pytest.fixture

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/tests/test_recorder_build.py

@@ -234,6 +234,42 @@ def test_the_signature_turns_the_hardened_runtime_on(bin_dir):
     assert fake.calls[-1][0][fake.calls[-1][0].index("--options") + 1] == "runtime"
 
 
+def test_the_hardened_runtime_is_signed_with_the_microphone_entitlement(bin_dir):
+    """Under the hardened runtime, AVCaptureDevice.requestAccess is refused
+    on the spot — no dialog, status stays notDetermined — unless the binary
+    declares com.apple.security.device.audio-input. Seen live on 2026-09-02:
+    every first dictation ended in "The recorder did not start"."""
+    import plistlib
+
+    fake = FakeToolchain()
+
+    install_module.build_recorder(bin_dir=bin_dir, runner=fake)
+
+    argv = fake.calls[-1][0]
+    assert "--entitlements" in argv
+    entitlements = Path(argv[argv.index("--entitlements") + 1])
+    assert entitlements == install_module.RECORDER_ENTITLEMENTS
+    with entitlements.open("rb") as f:
+        declared = plistlib.load(f)
+    assert declared == {"com.apple.security.device.audio-input": True}
+
+
+def test_a_changed_entitlements_file_forces_a_rebuild(bin_dir, tmp_path, monkeypatch):
+    """The entitlements are part of the signature, so they are part of the
+    recorder's identity: change them and the bundle must be rebuilt (and
+    the user told to re-grant), exactly like a source change."""
+    copy = tmp_path / "Recorder.entitlements"
+    shutil.copy(install_module.RECORDER_ENTITLEMENTS, copy)
+    monkeypatch.setattr(install_module, "RECORDER_ENTITLEMENTS", copy)
+
+    assert install_module.build_recorder(bin_dir=bin_dir, runner=FakeToolchain())[0] == "built"
+    assert install_module.build_recorder(bin_dir=bin_dir, runner=FakeToolchain())[0] == "current"
+
+    copy.write_text(copy.read_text(encoding="utf-8") + "\n", encoding="utf-8")
+
+    assert install_module.build_recorder(bin_dir=bin_dir, runner=FakeToolchain())[0] == "rebuilt"
+
+
 def test_the_compile_argv_is_a_list_naming_only_our_own_paths(bin_dir):
     fake = FakeToolchain()
 

vocalize_cli-0.10.1/tests/test_uv_path.py

@@ -0,0 +1,62 @@
+"""`vocalize.local.uv_path()`: PATH, then ~/.local/bin, then Homebrew.
+
+The Quick Actions run under a Services environment whose PATH is bare, so
+a Homebrew uv (Apple silicon or Intel) has to be found by name — seen live
+on 2026-09-02, when every hotkey dictation ended in "uv is not installed"
+while the same command worked from a terminal.
+"""
+
+import shutil
+from pathlib import Path
+
+import pytest
+
+from vocalize import local
+
+
+@pytest.fixture
+def off_path(monkeypatch, tmp_path):
+    """Nothing on PATH and an empty home, so only the fallbacks can answer."""
+    monkeypatch.setattr(shutil, "which", lambda name: None)
+    monkeypatch.setenv("HOME", str(tmp_path / "home"))
+    return tmp_path
+
+
+def test_path_wins(monkeypatch, tmp_path):
+    on_path = tmp_path / "uv"
+    on_path.write_text("")
+    monkeypatch.setattr(shutil, "which", lambda name: str(on_path) if name == "uv" else None)
+
+    assert local.uv_path() == str(on_path)
+
+
+def test_the_installer_spot_in_home_is_tried_before_homebrew(off_path, monkeypatch):
+    own = off_path / "home" / ".local" / "bin" / "uv"
+    own.parent.mkdir(parents=True)
+    own.write_text("")
+    homebrew = off_path / "opt" / "homebrew" / "bin" / "uv"
+    homebrew.parent.mkdir(parents=True)
+    homebrew.write_text("")
+    monkeypatch.setattr(local, "UV_FALLBACKS", (homebrew,))
+
+    assert local.uv_path() == str(own)
+
+
+def test_a_homebrew_uv_is_found_off_path(off_path, monkeypatch):
+    missing = off_path / "usr" / "local" / "bin" / "uv"
+    homebrew = off_path / "opt" / "homebrew" / "bin" / "uv"
+    homebrew.parent.mkdir(parents=True)
+    homebrew.write_text("")
+    monkeypatch.setattr(local, "UV_FALLBACKS", (homebrew, missing))
+
+    assert local.uv_path() == str(homebrew)
+
+
+def test_no_uv_anywhere_is_none(off_path, monkeypatch):
+    monkeypatch.setattr(local, "UV_FALLBACKS", (off_path / "nope" / "uv",))
+
+    assert local.uv_path() is None
+
+
+def test_the_shipped_fallbacks_are_homebrew_on_both_architectures():
+    assert local.UV_FALLBACKS == (Path("/opt/homebrew/bin/uv"), Path("/usr/local/bin/uv"))

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/vocalize/__init__.py

@@ -7,4 +7,4 @@ formatting into something that actually sounds good spoken aloud
 which is close to useless).
 """
 
-__version__ = "0.10.0"
+__version__ = "0.10.1"

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/vocalize/dictate.py

@@ -75,6 +75,16 @@ _WORKDIR_PREFIX = "vocalize-dictate-"
 # A second press this soon after the first is the user changing their mind,
 # not the end of a sentence (design § Key flows).
 _CANCEL_WINDOW = 2.0
+# ...but a press this soon after the *previous press* is the key still being
+# held: macOS re-fires a Service shortcut at its key-repeat rate, and every
+# repeat used to land as a cancel, then a fresh start, for as long as the
+# chord was down. The runner executes presses serially, so the gap between
+# a press ending and the queued repeat beginning is one process start-up
+# (~0.3 s here); this has to be comfortably longer than that and shorter
+# than a deliberate second tap. The stamp lives outside the session so it
+# also covers repeats arriving while a stop is being finished.
+_DEBOUNCE = 1.0
+_PRESS_NAME = "dictate.press"
 
 # How long the first press waits for the recorder to say it started. Also
 # the window in which a second press treats a missing `rec.pid` as "still
@@ -967,13 +977,46 @@ def _finish_take(workdir: Path, stt: dict) -> tuple[str | None, bool]:
 # --- the toggle state machine -----------------------------------------
 
 
+def _stamp_press() -> None:
+    """Record the moment as the latest press. Best effort: a stamp that
+    cannot be written simply never debounces."""
+    try:
+        audio.ensure_private_dir(CACHE_DIR)
+        (CACHE_DIR / _PRESS_NAME).write_text(f"{time.time()}\n", encoding="utf-8")
+    except OSError:
+        pass
+
+
+def _is_key_repeat() -> bool:
+    """Whether this press arrived within `_DEBOUNCE` of the previous stamp.
+
+    The Services runner executes presses one after another, so a repeat
+    queued behind a running press starts the moment that press *ends* —
+    which is why `toggle` stamps on the way out as well as on the way in.
+    A held key keeps refreshing the stamp and stays ignored until it is
+    released.
+    """
+    now = time.time()
+    try:
+        last = float((CACHE_DIR / _PRESS_NAME).read_text(encoding="utf-8").strip())
+    except (OSError, ValueError):
+        last = 0.0
+    _stamp_press()
+    return now - last < _DEBOUNCE
+
+
 def toggle(stt: dict) -> int:
     """One press of the dictation hotkey. Returns the process exit code."""
-    workdir = Path(tempfile.mkdtemp(prefix=_WORKDIR_PREFIX))
-    if _claim_session(workdir):
-        return _start(workdir, stt)
-    shutil.rmtree(workdir, ignore_errors=True)
-    return _second_press(stt)
+    if _is_key_repeat():
+        return 0
+    try:
+        workdir = Path(tempfile.mkdtemp(prefix=_WORKDIR_PREFIX))
+        if _claim_session(workdir):
+            return _start(workdir, stt)
+        shutil.rmtree(workdir, ignore_errors=True)
+        return _second_press(stt)
+    finally:
+        _stamp_press()  # a repeat queued behind this press begins right now
 
 
 def _start(workdir: Path, stt: dict) -> int:

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/vocalize/local/__init__.py

@@ -11,6 +11,10 @@ from __future__ import annotations
 import shutil
 from pathlib import Path
 
+# Where uv lives when it is on neither PATH nor in its own installer's
+# spot (~/.local/bin): Homebrew on Apple silicon, then on Intel.
+UV_FALLBACKS = (Path("/opt/homebrew/bin/uv"), Path("/usr/local/bin/uv"))
+
 
 def uv_path() -> str | None:
     """uv's executable, or None. PATH first, then its default install spot.
@@ -21,5 +25,9 @@ def uv_path() -> str | None:
     found = shutil.which("uv")
     if found:
         return found
-    fallback = Path.home() / ".local" / "bin" / "uv"
-    return str(fallback) if fallback.is_file() else None
+    # A Services (Quick Action) environment has a bare PATH, so the usual
+    # install spots are tried by name: uv's own installer, then Homebrew.
+    for fallback in (Path.home() / ".local" / "bin" / "uv", *UV_FALLBACKS):
+        if fallback.is_file():
+            return str(fallback)
+    return None

{vocalize_cli-0.10.0 → vocalize_cli-0.10.1}/vocalize/local/install.py

@@ -315,11 +315,13 @@ def selftest(
 _RECORDER_DIR = Path(__file__).resolve().parent.parent / "recorder"
 RECORDER_SOURCE = _RECORDER_DIR / "VocalizeRecorder.swift"
 RECORDER_PLIST_TEMPLATE = _RECORDER_DIR / "Info.plist.in"
+RECORDER_ENTITLEMENTS = _RECORDER_DIR / "Recorder.entitlements"
 
 BIN_DIR = Path.home() / ".cache" / "vocalize" / "bin"
 BUNDLE_NAME = "Vocalize Recorder.app"
 RECORDER_STAMP_NAME = ".recorder"
-RECORDER_STAMP_VERSION = 2
+# 3: the entitlements joined the fingerprint (0.10.0 signed without them).
+RECORDER_STAMP_VERSION = 3
 
 _BUILD_TIMEOUT = 600
 
@@ -369,6 +371,7 @@ def _recorder_fingerprint() -> dict:
         "stamp_version": RECORDER_STAMP_VERSION,
         "source_sha256": _sha256_of(RECORDER_SOURCE),
         "plist_sha256": _sha256_of(RECORDER_PLIST_TEMPLATE),
+        "entitlements_sha256": _sha256_of(RECORDER_ENTITLEMENTS),
     }
 
 
@@ -525,7 +528,7 @@ def build_recorder(
     through a fake compiler: nothing here should ever need Xcode to be
     installed on the machine running the suite.
     """
-    if not RECORDER_SOURCE.is_file() or not RECORDER_PLIST_TEMPLATE.is_file():
+    if not all(p.is_file() for p in (RECORDER_SOURCE, RECORDER_PLIST_TEMPLATE, RECORDER_ENTITLEMENTS)):
         raise InstallError(
             "This install of vocalize is missing the recorder source "
             f"({RECORDER_SOURCE.name}); reinstall vocalize to get it back."
@@ -570,14 +573,21 @@ def build_recorder(
         # --options runtime is the hardened runtime, which under the ad-hoc
         # signature refuses DYLD_INSERT_LIBRARIES — so nothing can inject a
         # dylib into the one process on this machine holding a microphone
-        # grant. It does *not* stop that bundle being launched directly:
+        # grant. The hardened runtime also refuses the microphone itself,
+        # silently and with no dialog, unless the signature carries
+        # com.apple.security.device.audio-input — hence --entitlements
+        # (0.10.0 shipped without it and no first dictation could start).
+        # It does *not* stop that bundle being launched directly:
         # the grant belongs to the bundle, and anything running as this user
         # can `open` it with its own --out and record. That is inherent to
         # DEC-001 and is stated in docs/dictation.md § Privacy; there is no
         # code mitigation, only `local uninstall --stt` plus revoking the
         # grant in System Settings.
         _run_build_step(
-            ["codesign", "-s", "-", "--force", "--options", "runtime", str(staging)],
+            [
+                "codesign", "-s", "-", "--force", "--options", "runtime",
+                "--entitlements", str(RECORDER_ENTITLEMENTS), str(staging),
+            ],
             runner, _CLT_HINT, "signed",
         )
         _swap_in(staging, bundle)

vocalize_cli-0.10.1/vocalize/recorder/Recorder.entitlements

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.security.device.audio-input</key>
+	<true/>
+</dict>
+</plist>

vocalize_cli-0.10.0/docs/roadmap.md

@@ -1,22 +0,0 @@
-# Roadmap
-
-Future work, with the research behind each item. Status legend: **planned** = analysed, decisions pending, nothing built; **spiked** = feasibility measured; **building**; **shipped**.
-
-| Item | Status | Tracking | Research |
-|---|---|---|---|
-| Hotkey-triggered local dictation (voice → text via a local Whisper model, Quick Action toggle, clipboard output, optional cleanup) | planned | [#1](https://github.com/matthager12-collab/vocalize/issues/1) | [analysis](next-features-analysis.md) · [full design](research/2026-09-01-dictation-design.md) · [voicebox findings](research/2026-09-01-voicebox-findings.md) |
-| Config portal (`vocalize portal`, stdlib local web page with a readiness checklist) — or the one-day `vocalize status` screen first | planned | [#1](https://github.com/matthager12-collab/vocalize/issues/1) | [analysis](next-features-analysis.md) · [full design](research/2026-09-01-config-portal-design.md) |
-
-## Open decisions (2026-09-01)
-
-1. Run the 3-hour dictation spike? It measures Whisper (`base.en` / `small.en` / `large-v3-turbo-q5_0`) against Apple's on-device recognizer on the owner's own voice with developer jargon, plus latency and RAM on the 8 GB M3. If Apple's engine wins, the Whisper branch is deleted from the plan.
-2. Portal (~50 h) or `vocalize status` (~1 day) first?
-3. Hotkey chord — proposed ⌃⌥⌘D.
-
-## Deferred on purpose
-
-Hold-to-talk (needs an event tap + Input Monitoring, ~6 h), auto-paste (Accessibility, ~2 h, belongs in the recorder bundle), Apple STT mode (~1.5 h), menu-bar agent (~12 h), local-LLM cleanup, resident/pre-warmed STT worker (only if the spike shows >2.5 s overhead), a native SwiftUI/Tauri app.
-
-## Sequencing suggestion
-
-Dictation first (the spike decides the engine, then ~20 h), portal or `status` second.