feat: voice dictation — Slack/Discord audio → text, supervised with the daemon (Parakeet-MLX / Canary-Qwen)

[kwliang1]

What

Adds voice dictation to Hydra: inbound audio attachments (Discord voice notes, Slack voice clips / audio uploads) are transcribed to text so you can dictate prompts to Claude alongside text and images. Claude has no native audio input, so the daemon transcribes first and merges the result as a [voice transcript] ... block; the original audio stays in downloaded_files.

Rebased on the latest upstream main (the hydra CLI, Slack Home tab, markdown chunking, etc.). The unrelated proj:/dir: spawn-prefix commit that was previously on this branch is dropped — that's its own PR (upstream sf8193#60).

Integrated into daemon start (not a separate service to remember)

• hydra up starts the sidecar with the daemon (kicked off right after the daemon tmux spawn so the model loads while the byte comes up). hydra down stops it. Every hydra watchdog tick revives it. Legacy start-daemon.sh / watchdog.sh call the same path.
• All supervisors go through start-transcribe.sh --auto, one shared gate: explicit HYDRA_TRANSCRIBE_AUTOSTART=1/0 wins in both directions; when unset it starts the sidecar iff a real backend is set up (venv built) and quietly no-ops otherwise — machines without dictation never log a failure per watchdog cycle. After the one-time ./transcribe-server/setup.sh there is zero extra config.
• One shared tmux session (hydra-transcribe) serves every platform daemon — per-platform sessions would race for the same port.
• A crashed server parks instead of exiting: the session stays alive holding the error, so a broken config (bad port, missing ffmpeg, failed model download) fails once — not a model-load crash-loop every 120s watchdog tick. Fix the cause, tmux kill-session -t hydra-transcribe to retry.
• The mock backend is never auto-supervised (manual run or explicit AUTOSTART=1 only) — leftover test config can't keep canned transcripts flowing into real prompts. A remote HYDRA_TRANSCRIBE_URL disables local autostart.

Slack audio attachments

• Slack voice clips arrive as message events with subtype file_share/slack_audio and a files[] entry (mimetype: audio/mp4, .m4a); the gateway only filters bot_message, so they flow through downloadAttachments (bearer-auth url_private_download) into the transcription hook like any attachment.
• Detection covers Slack shapes: audio/mp4, audio/webm;codecs=opus (browser recordings), extension fallback for generic mimetypes only — a definitive non-audio MIME (video/mp4 screen recording) is never re-classified as voice. Both sidecar servers resample via ffmpeg, so m4a/ogg/webm all work.
• New transcribeDownloads tests pin the contract with a stubbed fetch: only audio files are POSTed, sidecar failure skips (never blocks delivery), the size cap is enforced before the network, the disabled flag short-circuits.

Packaged default (not opt-in)

• On by default on the daemon side. Whenever a transcription sidecar is reachable, voice notes are transcribed; when it isn't, audio passes through untouched (fetch fails fast and is skipped; a live-but-slow sidecar delays only the voice message itself, bounded by HYDRA_TRANSCRIBE_TIMEOUT_MS). HYDRA_TRANSCRIBE_ENABLED=0 opts out.
• Self-hosted, audio stays local. macOS (Apple Silicon) → Parakeet-MLX (default); Linux+GPU → NVIDIA Canary-Qwen 2.5B via NeMo. Swappable behind a one-line HTTP contract (POST /transcribe → {"text": ...}).

Hardening (3-lens adversarial review: engineering / ops blast-radius / security)

• The sidecar env gets only dictation keys from the state-dir .env (no more set -a sourcing that leaked bot tokens into the model server's environment); parsing matches shell sourcing (export prefix, quoted values verbatim, inline comments stripped).
• PATH forwarded into the tmux pane (launchd-frozen server env broke ffmpeg lookup); every interpolated value shell-quoted (shq); mock backend falls back to system python (asdf shims fail without a pinned version).
• transcribeFile checks size via statSync before reading (the cap protects daemon memory, not just sidecar latency); a URL without an explicit port binds the scheme default so a mismatch fails visibly instead of silently serving the wrong port; start-daemon.sh's sidecar step can't fail the script under set -e after a successful daemon start.
• Fixed a test-infra bug from the original branch: a module-level process.stderr.write stub swallowed every later test file's output (and hid a suite crash).

Try it now — no GPU

./start-transcribe.sh mock        # GPU-free stub (manual only — never auto-supervised)
# send a voice note -> Claude gets "[voice transcript] This is a mock transcription..."

Real model (one-time; needs ffmpeg)

./transcribe-server/setup.sh      # venv + the right backend for your platform
# done — the sidecar now starts and stays up with the daemon

Changes

• daemon/transcription.ts — audio detection + transcript merge (pure, unit-tested) + HTTP client; failures logged and skipped, never block delivery.
• daemon/router.ts — hook into buildNotificationPayload after attachment download; voice_transcript meta marker.
• cli/lifecycle.ts, cli/helpers.ts — sidecar supervision in hydra up / down / watchdog (startTranscribeAuto, shared transcribeTmux).
• start-transcribe.sh — --auto gate, shared session, park-on-crash, key-allowlisted .env extraction, shq quoting.
• start-daemon.sh, watchdog.sh — call the shared --auto path (replaces the watchdog's AUTOSTART=1 grep opt-in; sidecar step runs before the watchdog's early exits).
• transcribe-server/ — server_mlx.py (Parakeet-MLX), server.py (Canary-Qwen via NeMo + ffmpeg), mock_server.py (stdlib stub), setup.sh, requirements*.txt, README.md.
• daemon/__tests__/transcription.test.ts — helper tests + Slack shapes + transcribeDownloads with stubbed fetch + proper env save/restore.
• .env.example, README.md.

Verified: bun build clean on daemon.ts / bridge.ts / cli/hydra.ts; bun test → 298/298; mock sidecar e2e over the real code path (transcribeDownloads → multipart POST → merge), incl. sidecar-down fail-fast; live checks of the full --auto gate matrix, park-on-crash (forced bind failure → parked once, no respawn), .env parsing edge cases, no token leak into the sidecar env (ps eww), hydra watchdog starting and hydra down stopping the sidecar. Reviewed by 3 parallel independent agents (engineering / ops / security) over 4 rounds until 2 successive clean rounds.

🤖 Generated with Claude Code