@sma1lboy/rove 0.9.281-next.31 → 0.9.282

package/dist/cli/rove.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import{join as l}from"node:path";import{createInterface as a}from"node:readline/promises";import{pathToFileURL as ss}from"node:url";import{spawnSync as Q}from"node:child_process";import{constants as e,accessSync as V}from"node:fs";import{homedir as R}from"node:os";import{basename as o,delimiter as I,dirname as U,join as y}from"node:path";import{fileURLToPath as T}from"node:url";var H={$schema:"https://json.schemastore.org/package.json",name:"@sma1lboy/rove",version:"0.9.280",description:"Rove — the agent multiplexer for your terminal. Run coding agents on parallel tasks with isolated worktrees and persistent sessions.",keywords:["terminal","tui","cli","multiplexer","ai-agents","coding-agent","ai-coding-assistant","agentic-ai","parallel-agents","git-worktree","claude-code","codex","llm","developer-tools"],type:"module",packageManager:"bun@1.3.13",bin:{rove:"dist/cli/rove.js"},files:["dist/cli","dist/completions","dist/web","dist/web-ui","dist/skills","dist/*.wav","README.md","LICENSE"],publishConfig:{access:"public"},repository:{type:"git",url:"git+https://github.com/Sma1lboy/rove.git"},homepage:"https://rove.run",bugs:{url:"https://github.com/Sma1lboy/rove/issues"},engines:{bun:">=1.3.11"},scripts:{dev:"ROVE_DEV=1 bun --conditions=browser ./src/cli/rove.ts","dev:mock":"ROVE_DEV=1 bun ./src/tui-react/mock/host.tsx","dev:sandbox":"bun run scripts/dev-sandbox.ts run","dev:sandbox:reset":"bun run scripts/dev-sandbox.ts reset",build:"bun run scripts/build.ts","build:rubric":"bun run scripts/build-tier-rubric.ts",compile:"bun run scripts/compile.ts",typecheck:"tsc --noEmit","check-i18n":"bun run scripts/check-i18n.ts",test:"bun run test:fast && bun run test:socket","perf:golden":"bun scripts/perf-golden.ts","pty:soak":"bun scripts/pty-soak.ts","test:fast":"vitest run --passWithNoTests --minWorkers=1 --maxWorkers=8","test:socket":"ROVE_INCLUDE_SOCKET=1 vitest run test/daemon --pool forks --minWorkers=1 --maxWorkers=4 --passWithNoTests","test:socket:coverage":"ROVE_INCLUDE_SOCKET=1 ROVE_COVERAGE_DAEMON=1 vitest run test/daemon --coverage --pool forks --minWorkers=1 --maxWorkers=4 --passWithNoTests","test:behavior":"ROVE_INCLUDE_BEHAVIOR=1 vitest run test/behavior --pool forks --minWorkers=1 --maxWorkers=1 --retry=2 --passWithNoTests","test:render":"bun scripts/render-track.mjs",coverage:"vitest run --coverage --passWithNoTests",bench:"vitest bench --run",lint:"biome check .",knip:"knip-bun",postinstall:"bun run scripts/check-preview-deps.ts || true",prepublishOnly:"bun run typecheck && bun run build","plugin-sandbox":"bun run scripts/plugin-sandbox.ts"},"//":"biome.json + bunfig.toml live at the monorepo root since they apply repo-wide; bun.lock also lives at root (workspace-shared).",dependencies:{"@ansi-tools/parser":"^1.0.15","@opentui/core":"0.4.3","@opentui/react":"0.4.3","@xterm/addon-serialize":"^0.14.0","@xterm/addon-unicode11":"^0.9.0","@xterm/headless":"^6.0.0",react:"^19.2.8","smol-toml":"^1.7.1",ws:"^8.21.3"},optionalDependencies:{"node-pty":"^1.1.0"},devDependencies:{"@biomejs/biome":"1.9.4","@sma1lboy/rove-daemon":"0.7.23","@tsconfig/bun":"1.0.11","@types/bun":"1.3.14","@types/node":"25.6.2","@types/react":"^19.2.0","@vitest/coverage-v8":"2.1.9",knip:"^6.14.2","react-devtools-core":"^7.0.1","rove-bridge":"0.0.41","rove-weixin":"0.0.41",typescript:"5.8.2",vitest:"2.1.9"},trustedDependencies:[]};var q="rove";var k=q;var z="ROVE_BUN",_="ROVE_NO_BUN_BOOTSTRAP",F="ROVE_SKIP_BUN_CHECK",$=H.engines.bun.match(/\d+\.\d+\.\d+/)?.[0]??"0.0.0",L=(s)=>{try{return V(s,e.X_OK),!0}catch{return!1}},B=(s)=>s==="win32"?"bun.exe":"bun",f=(s)=>{let t=Q(s,["--version"],{encoding:"utf8",timeout:5000});if(t.error||t.status!==0)return null;return t.stdout?.split(`
-`)[0]?.trim()??""};function J(s){return s.trim().match(/^v?(\d+\.\d+\.\d+)/)?.[1]??null}function X(s,t=$){let c=J(s),W=J(t);if(!c||!W)return!0;let b=c.split(".").map(Number),g=W.split(".").map(Number);for(let p=0;p<3;p++){let r=b[p]??0,i=g[p]??0;if(r!==i)return r>i}return!0}function Y(s=process.env){return s[F]==="1"}function A(s={}){let t=s.env??process.env,c=s.platform??process.platform,W=s.home??t.HOME??t.USERPROFILE??R(),b=B(c),g=[],p=t[z]?.trim();if(p)g.push(p);for(let G of(t.PATH??t.Path??"").split(I))if(G)g.push(y(G,b));let r=t.BUN_INSTALL?.trim();if(r)g.push(y(r,"bin",b));if(W)g.push(y(W,".bun","bin",b));let i=s.launcherDir;if(i)g.push(y(i,"..","..","node_modules","bun","bin",b)),g.push(y(i,"..","..","..","bun","bin",b));return g}function N(s={}){let t=s.isExecutable??L;return A(s).find((c)=>t(c))??null}function Z(s={}){let t=s.isExecutable??L,c=s.bunVersionOf??f;if(Y(s.env??process.env))return{bun:N(s),stale:null,unusable:null};let W=null,b=null;for(let g of A(s)){if(!t(g))continue;let p=c(g);if(p===null){b??=g;continue}if(X(p))return{bun:g,stale:W,unusable:b};W??={path:g,version:J(p)??p}}return{bun:null,stale:W,unusable:b}}function h(s){return U(T(s))}function C(s){return o(T(s)).replace(/\.[cm]?[jt]s$/,"")}function n(s=process.platform){return s==="win32"?["powershell","-NoProfile","-Command","irm bun.sh/install.ps1 | iex"]:["bash","-c","curl -fsSL https://bun.sh/install | bash"]}function D(s=k,t=process.platform){let c=t==="win32"?'powershell -c "irm bun.sh/install.ps1 | iex"':"curl -fsSL https://bun.sh/install | bash";return[`${s}: Rove runs on the Bun runtime, and no Bun was found on this machine.`,"","Install Bun, then run this command again:",`  ${c}`,"  npm install -g bun          # any platform, if you already have npm","","Or install Bun and Rove together in one step:","  curl -fsSL https://rove.run/install.sh | sh","",`Already have Bun somewhere unusual? Point Rove at it: ${z}=/path/to/bun`,""].join(`
+import{join as l}from"node:path";import{createInterface as a}from"node:readline/promises";import{pathToFileURL as ss}from"node:url";import{spawnSync as Q}from"node:child_process";import{constants as P,accessSync as V}from"node:fs";import{homedir as o}from"node:os";import{basename as R,delimiter as I,dirname as U,join as y}from"node:path";import{fileURLToPath as T}from"node:url";var H={$schema:"https://json.schemastore.org/package.json",name:"@sma1lboy/rove",version:"0.9.282",description:"Rove — the agent multiplexer for your terminal. Run coding agents on parallel tasks with isolated worktrees and persistent sessions.",keywords:["terminal","tui","cli","multiplexer","ai-agents","coding-agent","ai-coding-assistant","agentic-ai","parallel-agents","git-worktree","claude-code","codex","llm","developer-tools"],type:"module",packageManager:"bun@1.3.13",bin:{rove:"dist/cli/rove.js"},files:["dist/cli","dist/completions","dist/web","dist/web-ui","dist/skills","dist/voice","dist/*.wav","README.md","LICENSE"],publishConfig:{access:"public"},repository:{type:"git",url:"git+https://github.com/Sma1lboy/rove.git"},homepage:"https://rove.run",bugs:{url:"https://github.com/Sma1lboy/rove/issues"},engines:{bun:">=1.3.11"},scripts:{dev:"ROVE_DEV=1 bun --conditions=browser ./src/cli/rove.ts","dev:mock":"ROVE_DEV=1 bun ./src/tui-react/mock/host.tsx","dev:sandbox":"bun run scripts/dev-sandbox.ts run","dev:sandbox:reset":"bun run scripts/dev-sandbox.ts reset",build:"bun run scripts/build.ts","build:rubric":"bun run scripts/build-tier-rubric.ts",compile:"bun run scripts/compile.ts",typecheck:"tsc --noEmit","check-i18n":"bun run scripts/check-i18n.ts",test:"bun run test:fast && bun run test:socket","perf:golden":"bun scripts/perf-golden.ts","pty:soak":"bun scripts/pty-soak.ts","test:fast":"vitest run --passWithNoTests --minWorkers=1 --maxWorkers=8","test:socket":"ROVE_INCLUDE_SOCKET=1 vitest run test/daemon --pool forks --minWorkers=1 --maxWorkers=4 --passWithNoTests","test:socket:coverage":"ROVE_INCLUDE_SOCKET=1 ROVE_COVERAGE_DAEMON=1 vitest run test/daemon --coverage --pool forks --minWorkers=1 --maxWorkers=4 --passWithNoTests","test:behavior":"ROVE_INCLUDE_BEHAVIOR=1 vitest run test/behavior --pool forks --minWorkers=1 --maxWorkers=1 --retry=2 --passWithNoTests","test:render":"bun scripts/render-track.mjs",coverage:"vitest run --coverage --passWithNoTests",bench:"vitest bench --run",lint:"biome check .",knip:"knip-bun",postinstall:"bun run scripts/check-preview-deps.ts || true",prepublishOnly:"bun run typecheck && bun run build","plugin-sandbox":"bun run scripts/plugin-sandbox.ts"},"//":"biome.json + bunfig.toml live at the monorepo root since they apply repo-wide; bun.lock also lives at root (workspace-shared).",dependencies:{"@ansi-tools/parser":"^1.0.15","@opentui/core":"0.4.3","@opentui/react":"0.4.3","@xterm/addon-serialize":"^0.14.0","@xterm/addon-unicode11":"^0.9.0","@xterm/headless":"^6.0.0",react:"^19.2.8","smol-toml":"^1.7.1",ws:"^8.21.3"},optionalDependencies:{"node-pty":"^1.1.0"},devDependencies:{"@biomejs/biome":"1.9.4","@sma1lboy/rove-daemon":"0.7.23","@tsconfig/bun":"1.0.11","@types/bun":"1.3.14","@types/node":"25.6.2","@types/react":"^19.2.0","@vitest/coverage-v8":"2.1.9",knip:"^6.14.2","react-devtools-core":"^7.0.1","rove-bridge":"0.0.43","rove-weixin":"0.0.43",typescript:"5.8.2",vitest:"2.1.9"},trustedDependencies:[]};var q="rove";var k=q;var z="ROVE_BUN",_="ROVE_NO_BUN_BOOTSTRAP",F="ROVE_SKIP_BUN_CHECK",$=H.engines.bun.match(/\d+\.\d+\.\d+/)?.[0]??"0.0.0",L=(s)=>{try{return V(s,P.X_OK),!0}catch{return!1}},B=(s)=>s==="win32"?"bun.exe":"bun",f=(s)=>{let t=Q(s,["--version"],{encoding:"utf8",timeout:5000});if(t.error||t.status!==0)return null;return t.stdout?.split(`
+`)[0]?.trim()??""};function J(s){return s.trim().match(/^v?(\d+\.\d+\.\d+)/)?.[1]??null}function X(s,t=$){let c=J(s),W=J(t);if(!c||!W)return!0;let b=c.split(".").map(Number),g=W.split(".").map(Number);for(let i=0;i<3;i++){let r=b[i]??0,x=g[i]??0;if(r!==x)return r>x}return!0}function Y(s=process.env){return s[F]==="1"}function A(s={}){let t=s.env??process.env,c=s.platform??process.platform,W=s.home??t.HOME??t.USERPROFILE??o(),b=B(c),g=[],i=t[z]?.trim();if(i)g.push(i);for(let G of(t.PATH??t.Path??"").split(I))if(G)g.push(y(G,b));let r=t.BUN_INSTALL?.trim();if(r)g.push(y(r,"bin",b));if(W)g.push(y(W,".bun","bin",b));let x=s.launcherDir;if(x)g.push(y(x,"..","..","node_modules","bun","bin",b)),g.push(y(x,"..","..","..","bun","bin",b));return g}function N(s={}){let t=s.isExecutable??L;return A(s).find((c)=>t(c))??null}function Z(s={}){let t=s.isExecutable??L,c=s.bunVersionOf??f;if(Y(s.env??process.env))return{bun:N(s),stale:null,unusable:null};let W=null,b=null;for(let g of A(s)){if(!t(g))continue;let i=c(g);if(i===null){b??=g;continue}if(X(i))return{bun:g,stale:W,unusable:b};W??={path:g,version:J(i)??i}}return{bun:null,stale:W,unusable:b}}function h(s){return U(T(s))}function C(s){return R(T(s)).replace(/\.[cm]?[jt]s$/,"")}function n(s=process.platform){return s==="win32"?["powershell","-NoProfile","-Command","irm bun.sh/install.ps1 | iex"]:["bash","-c","curl -fsSL https://bun.sh/install | bash"]}function D(s=k,t=process.platform){let c=t==="win32"?'powershell -c "irm bun.sh/install.ps1 | iex"':"curl -fsSL https://bun.sh/install | bash";return[`${s}: Rove runs on the Bun runtime, and no Bun was found on this machine.`,"","Install Bun, then run this command again:",`  ${c}`,"  npm install -g bun          # any platform, if you already have npm","","Or install Bun and Rove together in one step:","  curl -fsSL https://rove.run/install.sh | sh","",`Already have Bun somewhere unusual? Point Rove at it: ${z}=/path/to/bun`,""].join(`
 `)}function j(s,t,c=k){return[`${c}: this machine's Bun is too old for Rove — found ${t} at ${s}, need ${$} or newer.`,"","Rove's terminals are built on Bun's PTY API. An older Bun ignores it silently,","so every terminal and engine tab would open empty and stay empty.","","Upgrade Bun, then run this command again:","  bun upgrade                 # Bun installed itself (~/.bun)","  brew upgrade bun            # Homebrew","  npm install -g bun@latest   # npm-managed Bun","",`Have a newer Bun elsewhere? Point Rove at it: ${z}=/path/to/bun`,`Run on this one anyway (unsupported, terminals will be blank): ${F}=1`,""].join(`
 `)}function v(s,t=k){return[`${t}: the Bun at ${s} could not be run — \`${s} --version\` failed or never returned.`,"","Rove skipped it rather than starting through it, which would hang or fail","with a message from that binary instead of this one.","","Reinstall Bun, then run this command again:","  curl -fsSL https://bun.sh/install | bash","",`Have a working Bun elsewhere? Point Rove at it: ${z}=/path/to/bun`,""].join(`
 `)}function w(s=process.env,t=process.stdin,c=process.stdout){if(s[_]==="1")return!1;if(s.CI==="true"||s.CI==="1")return!1;return Boolean(t.isTTY&&c.isTTY)}function M(s={},t=Q){let c=s.platform??process.platform,[W,...b]=n(c);if(!W)return null;let g=t(W,b,{stdio:"inherit"});if(g.error||g.status!==0)return null;return Z(s).bun}function u(s){if(typeof s.status==="number")return s.status;if(s.signal)return 128+(Object.hasOwn(K,s.signal)?K[s.signal]:0);return 1}var K={SIGINT:2,SIGQUIT:3,SIGKILL:9,SIGTERM:15};function S(s,t,c,W=Q){let b=W(s,[t,...c],{stdio:"inherit"});if(b.error)return process.stderr.write(`rove: could not start Bun at ${s}: ${b.error.message}. Check that this path is executable, or reinstall Bun from https://bun.sh.
-`),1;return u(b)}var d=h(import.meta.url),x=C(import.meta.url),m=l(d,`${x}-run.js`);async function ts(s){let t=a({input:process.stdin,output:process.stdout});try{let c=(await t.question(s)).trim().toLowerCase();return c===""||c==="y"||c==="yes"}finally{t.close()}}async function cs(){let s={launcherDir:d},t=Z(s);if(t.bun||!w())return t;let c=t.stale?`${x}: Bun ${t.stale.version} is too old for Rove (needs ${$}+). Install the latest Bun now? [Y/n] `:`${x}: Rove runs on the Bun runtime, and none is installed. Install Bun now? [Y/n] `;if(!await ts(c))return t;return{bun:M(s),stale:t.stale,unusable:t.unusable}}var O=globalThis.Bun;if(O){let s=O.version;if(s&&!Y()&&!X(s))process.stderr.write(j(process.execPath,s,x)),process.exit(1);await import(ss(m).href)}else{let{bun:s,stale:t,unusable:c}=await cs();if(!s){let W=t?j(t.path,t.version,x):c?v(c,x):D(x);process.stderr.write(W),process.exit(1)}process.exit(S(s,m,process.argv.slice(2)))}
+`),1;return u(b)}var O=h(import.meta.url),p=C(import.meta.url),d=l(O,`${p}-run.js`);async function ts(s){let t=a({input:process.stdin,output:process.stdout});try{let c=(await t.question(s)).trim().toLowerCase();return c===""||c==="y"||c==="yes"}finally{t.close()}}async function cs(){let s={launcherDir:O},t=Z(s);if(t.bun||!w())return t;let c=t.stale?`${p}: Bun ${t.stale.version} is too old for Rove (needs ${$}+). Install the latest Bun now? [Y/n] `:`${p}: Rove runs on the Bun runtime, and none is installed. Install Bun now? [Y/n] `;if(!await ts(c))return t;return{bun:M(s),stale:t.stale,unusable:t.unusable}}var m=globalThis.Bun;if(m){let s=m.version;if(s&&!Y()&&!X(s))process.stderr.write(j(process.execPath,s,p)),process.exit(1);await import(ss(d).href)}else{let{bun:s,stale:t,unusable:c}=await cs();if(!s){let W=t?j(t.path,t.version,p):c?v(c,p):D(p);process.stderr.write(W),process.exit(1)}process.exit(S(s,d,process.argv.slice(2)))}

package/dist/skills/rove/SKILL.md

@@ -3,7 +3,7 @@ name: rove
 description: Use when controlling Rove tasks, parallel coding attempts, hosted agent sessions, task lifecycle, or the daemon-owned issue tracker from a shell. Also the ONLY channel for messaging another agent session on this machine — `rove api send`, never a peer/MCP side channel.
 ---
 
-<!-- rove-skill-version: 108 — bump in lockstep with ROVE_SKILL_VERSION (src/lib/skill-install.ts). -->
+<!-- rove-skill-version: 109 — bump in lockstep with ROVE_SKILL_VERSION (src/lib/skill-install.ts). -->
 
 # Rove shell control
 
@@ -309,9 +309,11 @@ Find your section by what you were ASKED, not by Rove's noun for it:
 | a prompt ends `[ROVE] … report with: rove api report`; tick a task unattended and want proof it reported, or skip a tick the task can't use | drive (`report`, `send --expect-report`, `send --if-runnable`) / read (`deliveries`, `should-run`) |
 | make / rename / retarget / land / close a task | create / edit / lifecycle |
 | materialize or adopt a checkout | worktree |
-| which engines exist, send Rove product feedback | discover / feedback |
+| which engines exist, report a Rove problem or idea | discover / feedback |
 | an error code came back, `nextCommandArgs` | Error codes |
 
+When the user says anything in Rove itself is awkward, broken or missing, offer to file it right away: draft a short title and body, show it, and on their OK run `rove feedback --kind bug|idea|question --title … --body-file -` (body on stdin), then share the URL. If it prints a prefilled link instead, hand that over and say to run `gh auth login`. Only for Rove; another project's bug is a `send` to its main task.
+
 Reach for `schema` when the binary and that file disagree.
 
 ```bash

package/dist/skills/rove/references/api-flags.md

@@ -433,7 +433,7 @@ schema       --verb --group --all
 engine-list  (none)
 repo-match   --origin --root --allow-fork
 repo-list    (none)
-feedback     --title(REQ) --body(REQ) --category(feedback)
+feedback     --title(REQ) --body(REQ) --kind(bug)
 ```
 <!-- generated:end -->
 
@@ -452,9 +452,12 @@ resolves to (`{ repo, fork?, checkouts, searched }`); `repo-list` lists a
 machine's repos by id (`{ repos: [{ id, primary, checkouts }] }`) — pass
 `--machine <alias>` to ask another machine.
 
-`feedback` opens a GitHub Discussion in the Rove repo through `gh` — Rove's own
-product feedback channel, not a way to file work for another project (that is
-a `send` to their main task; see SKILL.md).
+`feedback` files a GitHub issue on the Rove repo through `gh` (`--kind` picks the
+label: bug, idea → enhancement, question) and appends an environment block.
+It returns `{ filed: true, url, number }`; with no usable `gh` it returns
+`{ filed: false, url, hint }` where `url` is a prefilled new-issue link — hand
+it to the user. Rove's own product feedback channel, not a way to file work
+for another project (that is a `send` to their main task; see SKILL.md).
 
 ## Error codes
 

package/dist/voice/asr_server.py

@@ -0,0 +1,318 @@
+"""Dictation endpoint for rove's web client.
+
+The phone records 16 kHz mono PCM, rove-bridge POSTs the WAV here with the text of the
+conversation being dictated into, and this process returns the transcript. The recognizer is
+local Whisper unless `~/.rove/voice/config.json` names a cloud endpoint (`engine.py`); the
+vocabulary is `vocab.py`, sound-alike fixes `phonetic.py`. Everything this process keeps lives
+under `~/.rove/voice`.
+
+Run: `uv run --project scripts/voice --extra local scripts/voice/asr_server.py` (or Settings → Voice).
+Binds 127.0.0.1 only; the bridge is the one public surface.
+
+  POST /transcribe {wav: hex, conversation?, context?, language?} -> {text, raw, language, ...}
+  POST /stream {session, seq, pcm: hex int16, final?, conversation?, context?, language?}
+       -> {partial} per chunk, the /transcribe reply at final (live.py)
+  GET  /health
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import secrets
+import sys
+import threading
+import time
+import wave
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+import engine
+import learn
+import live
+import phonetic
+import polish
+import vocab
+
+PORT = int(os.environ.get("ROVE_VOICE_PORT", "8791"))
+MIN_AUDIO_SEC = 0.25
+SILENCE_RMS = 0.004  # 16-bit speech sits far above this; fan noise and dead mics do not.
+MAX_AUDIO_SEC = 240
+
+_ready = threading.Event()
+_warm_ms: float | None = None
+_error: str | None = None
+_backend: engine.Backend | None = None
+_config: dict[str, Any] = {}
+
+
+def read_token() -> str:
+    """One shared secret so a stray local process cannot drive the microphone path."""
+    path = engine.HOME / "token"
+    engine.HOME.mkdir(parents=True, exist_ok=True)
+    if not path.exists():
+        path.write_text(secrets.token_hex(24))
+        path.chmod(0o600)
+    return path.read_text().strip()
+
+
+def decode_wav(data: bytes) -> np.ndarray:
+    with wave.open(io.BytesIO(data)) as wav:
+        if wav.getnchannels() != 1:
+            raise ValueError("expected mono audio")
+        width = wav.getsampwidth()
+        rate = wav.getframerate()
+        frames = wav.readframes(wav.getnframes())
+    if width != 2:
+        raise ValueError(f"expected 16-bit samples, got {width * 8}-bit")
+    if rate != engine.SAMPLE_RATE:
+        raise ValueError(f"expected {engine.SAMPLE_RATE} Hz, got {rate}")
+    return np.frombuffer(frames, dtype="<i2").astype(np.float32) / 32768.0
+
+
+def silent(pcm: np.ndarray) -> bool:
+    return not len(pcm) or float(np.sqrt(np.mean(np.square(pcm)))) < SILENCE_RMS
+
+
+def dictate(
+    backend: engine.Backend,
+    pcm: np.ndarray,
+    *,
+    conversation: str | None,
+    draft: str | None,
+    language: str | None,
+    config: dict[str, Any],
+    final: bool = True,
+) -> dict[str, Any]:
+    """One dictation: rank the vocabulary, recognize, normalize the script, then fix the English:
+    stored mishearings first, then whatever lands close to a term the recognizer was given. A final
+    take is then cleaned up by a chat model when config.json asks for it (polish.py); a live take's
+    partials never are."""
+    stored = vocab.load()["terms"]
+    terms = vocab.rank(conversation, draft, stored, backend.max_terms)
+    # Measured on large-v3: terms in the prompt cost a term when they were not said (68 -> 67 with the
+    # conversation's, 68 -> 64 with 15 learned ones) and gain less (70) than using them only to correct
+    # (72, and 68 when not said). Cloud recognizers take the prompt without that cost, so they get it by default.
+    in_prompt = config.get("promptContext", not isinstance(backend, engine.LocalWhisper))
+    hinted = terms if in_prompt else vocab.rank(None, draft, stored, backend.max_terms, rest=False)
+    raw, detected = backend.transcribe(pcm, hinted, language)
+    text = engine.simplified(raw) if config.get("simplified", True) else raw
+    text = vocab.correct(vocab.apply_spoken(text, stored), terms, fuzzy=config.get("fuzzy", True))
+    # Bench: +1 to +3 terms when the conversation holds them, no change otherwise (phonetic.py).
+    if config.get("phonetic", True):
+        text = phonetic.correct(text, terms)
+    out = {"text": text, "raw": raw, "language": detected, "terms": len(terms)}
+    if final and polish.enabled(config):
+        started = time.monotonic()
+        polished, error = polish.polish(text, terms, config)
+        out |= {"text": polished, "unpolished": text, "polishMs": round((time.monotonic() - started) * 1000)}
+        if error:
+            out["polishError"] = error
+            sys.stderr.write(f"voice: polish failed, kept the recognizer's text: {error}\n")
+    return out
+
+
+def warm() -> None:
+    """A cold graph costs seconds; pay it at boot, not on the first press."""
+    global _warm_ms, _error, _backend, _config
+    started = time.monotonic()
+    try:
+        _config = engine.load_config()
+        _backend = engine.backend(_config)
+        if isinstance(_backend, engine.LocalWhisper):
+            _backend.transcribe(np.zeros(engine.SAMPLE_RATE, dtype=np.float32), [], "en")
+        engine.simplified("說")
+    except Exception as err:  # noqa: BLE001 - surfaced on /health, the server stays up
+        _error = str(err)
+        sys.stderr.write(f"voice: backend failed: {err}\n")
+        return
+    _warm_ms = round((time.monotonic() - started) * 1000)
+    _ready.set()
+
+
+class Handler(BaseHTTPRequestHandler):
+    token = ""
+
+    def log_message(self, fmt: str, *args: Any) -> None:  # noqa: A003 - stdlib signature
+        sys.stderr.write("voice %s\n" % (fmt % args))
+
+    def reply(self, code: int, body: dict[str, Any]) -> None:
+        data = json.dumps(body, ensure_ascii=False).encode()
+        self.send_response(code)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def do_GET(self) -> None:  # noqa: N802 - stdlib signature
+        # /health stays open: the bridge probes it before the user says anything.
+        if self.path != "/health":
+            self.reply(404, {"error": "not_found"})
+            return
+        name = _backend.name if _backend else None
+        body = {"ready": _ready.is_set(), "model": name, "warm_ms": _warm_ms, "error": _error}
+        # Which copy answers: two bridges (release and a checkout) may each have started one.
+        self.reply(200, {**body, "pid": os.getpid(), "code": str(Path(__file__).resolve().parent)})
+
+    def body(self) -> dict[str, Any] | None:
+        if self.headers.get("x-voice-token", "") != self.token:
+            self.reply(401, {"error": "bad_token"})
+            return None
+        length = int(self.headers.get("content-length") or 0)
+        if length <= 0 or length > 32 * 1024 * 1024:
+            self.reply(400, {"error": "bad_size"})
+            return None
+        try:
+            return json.loads(self.rfile.read(length))
+        except ValueError:
+            self.reply(400, {"error": "bad_json"})
+            return None
+
+    def do_POST(self) -> None:  # noqa: N802 - stdlib signature
+        routes = {
+            "/transcribe": self.transcribe,
+            "/stream": self.stream,
+            "/learn": self.learn_edit,
+            "/unlearn": self.unlearn_edit,
+        }
+        route = routes.get(self.path)
+        if route is None:
+            self.reply(404, {"error": "not_found"})
+            return
+        request = self.body()
+        if request is not None:
+            route(request)
+
+    def transcribe(self, request: dict[str, Any]) -> None:
+        try:
+            pcm = decode_wav(bytes.fromhex(request["wav"]))
+        except Exception as err:  # noqa: BLE001 - every failure is the caller's audio
+            self.reply(400, {"error": f"bad_audio: {err}"})
+            return
+        self.finish_take(pcm, request.get("conversation"), request.get("context"), request.get("language"))
+
+    def finish_take(self, pcm: np.ndarray, conversation: str | None, draft: str | None, language: str | None) -> None:
+        seconds = round(len(pcm) / engine.SAMPLE_RATE, 2)
+        if seconds < MIN_AUDIO_SEC:
+            self.reply(200, {"text": "", "reason": "too_short", "seconds": seconds})
+            return
+        if seconds > MAX_AUDIO_SEC:
+            self.reply(200, {"text": "", "reason": "too_long", "seconds": seconds})
+            return
+        if silent(pcm):
+            self.reply(200, {"text": "", "reason": "silent", "seconds": seconds})
+            return
+        if _backend is None or not _ready.is_set():
+            self.reply(503, {"error": _error or "warming up"})
+            return
+        started = time.monotonic()
+        try:
+            out = dictate(_backend, pcm, conversation=conversation, draft=draft, language=language, config=_config)
+        except Exception as err:  # noqa: BLE001 - report, never take the server down
+            self.reply(500, {"error": f"transcribe: {err}"})
+            return
+        ms = round((time.monotonic() - started) * 1000)
+        # Counts only, never the words: enough to see the conversation arrived and what a take cost.
+        heard = len(conversation or "")
+        terms = out["terms"]
+        sys.stderr.write(f"voice: {seconds}s audio, {heard} chars of conversation, {terms} terms, {ms} ms\n")
+        self.reply(200, {**out, "seconds": seconds, "ms": ms})
+
+    def stream(self, request: dict[str, Any]) -> None:
+        """One chunk of a live take (live.py): the text so far while it grows, the transcript at `final`."""
+        session, seq = request.get("session"), request.get("seq")
+        if not isinstance(session, str) or not isinstance(seq, int):
+            self.reply(400, {"error": "bad_args"})
+            return
+        try:
+            raw = bytes.fromhex(request.get("pcm") or "")
+            pcm = np.frombuffer(raw[: len(raw) // 2 * 2], dtype="<i2").astype(np.float32) / 32768.0
+            take = live.append(session, seq, pcm, request)
+        except live.Gap as err:
+            self.reply(409, {"error": f"gap: {err}"})
+            return
+        except ValueError as err:
+            self.reply(400, {"error": f"bad_audio: {err}"})
+            return
+        if request.get("final"):
+            live.finish(session)
+            self.finish_take(take.pcm(), take.conversation, take.draft, take.language)
+            return
+        backend = _backend
+        if backend is None or not _ready.is_set() or not live.due(take, backend):
+            self.reply(200, {"partial": None})
+            return
+        # Never queue behind another decode: the next chunk asks again.
+        if not engine.GPU.acquire(blocking=False):
+            self.reply(200, {"partial": None})
+            return
+        try:
+            take.decoded = take.samples
+            pcm = take.pcm()
+            text = (
+                ""
+                if silent(pcm)
+                else dictate(
+                    backend,
+                    pcm,
+                    conversation=take.conversation,
+                    draft=take.draft,
+                    language=take.language,
+                    config=_config,
+                    final=False,
+                )["text"]
+            )
+        except Exception as err:  # noqa: BLE001 - a failed partial only means no partial
+            sys.stderr.write(f"voice: partial failed: {err}\n")
+            text = None
+        finally:
+            engine.GPU.release()
+        self.reply(200, {"partial": text})
+
+    def learn_edit(self, request: dict[str, Any]) -> None:
+        """A sent message against the draft its takes left: the fixes inside them join the vocabulary."""
+        base, sent, spans = request.get("base"), request.get("sent"), request.get("spans")
+        if not isinstance(base, str) or not isinstance(sent, str) or not isinstance(spans, list):
+            self.reply(400, {"error": "bad_args"})
+            return
+        if not _config.get("learn", True):
+            self.reply(200, {"learned": []})
+            return
+        pairs = [(int(s[0]), int(s[1])) for s in spans if isinstance(s, list) and len(s) == 2]
+        added = learn.remember(learn.fixes(base, pairs, sent))
+        sys.stderr.write(f"voice: learned {len(added)} from an edit\n")
+        self.reply(200, {"learned": added})
+
+    def unlearn_edit(self, request: dict[str, Any]) -> None:
+        learned = request.get("learned")
+        if not isinstance(learned, list):
+            self.reply(400, {"error": "bad_args"})
+            return
+        self.reply(200, {"undone": learn.forget([x for x in learned if isinstance(x, dict)])})
+
+
+def main() -> None:
+    Handler.token = read_token()
+    try:
+        server = ThreadingHTTPServer(("127.0.0.1", PORT), Handler)
+    except OSError as err:
+        # Another sidecar already answers here; it serves every bridge on this machine.
+        sys.stderr.write(f"voice: port {PORT} is taken ({err}); leaving it to that process\n")
+        raise SystemExit(0) from err
+    pidfile = engine.HOME / "sidecar.pid"
+    pidfile.write_text(str(os.getpid()))
+    threading.Thread(target=warm, daemon=True).start()
+    sys.stderr.write(f"voice listening on http://127.0.0.1:{PORT}\n")
+    try:
+        server.serve_forever()
+    finally:
+        if pidfile.exists() and pidfile.read_text().strip() == str(os.getpid()):
+            pidfile.unlink()
+
+
+if __name__ == "__main__":
+    main()

package/dist/voice/engine.py

@@ -0,0 +1,174 @@
+"""The recognizer behind the sidecar: local Whisper by default, or any OpenAI-compatible
+`/audio/transcriptions` endpoint when `~/.rove/voice/config.json` names one.
+
+config.json, all keys optional:
+  {"backend": "local", "model": "mlx-community/whisper-large-v3-turbo"}   # faster, see LOCAL_MODEL
+  {"backend": "cloud", "baseURL": "https://openrouter.ai/api/v1", "model": "microsoft/mai-transcribe-2",
+   "apiKeyEnv": "OPENROUTER_API_KEY"}            # or "apiKey": "..."; the key never leaves this Mac
+  {"simplified": false}                         # keep Traditional characters as recognized
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import os
+import threading
+import urllib.error
+import urllib.request
+import uuid
+import wave
+from functools import cache
+from pathlib import Path
+from typing import Any, Protocol
+
+import numpy as np
+
+HOME = Path(os.environ.get("ROVE_VOICE_HOME") or Path.home() / ".rove" / "voice")
+SAMPLE_RATE = 16_000
+# Code-switch bench (bench.py, 82 terms): large-v3 68, 74 with the conversation's terms, p50 1.8 s;
+# turbo 63, 69 at best, p50 1.0 s. Turbo is the faster pick in config.json; it loses most when context is thin.
+LOCAL_MODEL = "mlx-community/whisper-large-v3-mlx"
+# Without this hint large-v3 often answers Mandarin in Traditional script; English is unaffected.
+ZH_GUARD = "以下是普通话的句子。"
+CLOUD_TIMEOUT_S = 30
+# One decode at a time on the GPU: the server answers on threads, and a live take's partials run
+# beside other requests. Reentrant so a caller can hold it across a whole dictation (live.py).
+GPU = threading.RLock()
+
+
+class Backend(Protocol):
+    name: str
+    max_terms: int
+
+    def transcribe(self, pcm: np.ndarray, terms: list[str], language: str | None) -> tuple[str, str | None]: ...
+
+
+def load_config() -> dict[str, Any]:
+    path = HOME / "config.json"
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text())
+
+
+class LocalWhisper:
+    """mlx-whisper on the Mac's GPU. The terms ride in the prompt, which Whisper reads as preceding
+    text: spelled-right terms there are the cheapest bias a decoder without a boost list accepts."""
+
+    max_terms = 60
+
+    def __init__(self, model: str) -> None:
+        self.model = model
+        self.name = f"local:{model}"
+
+    def transcribe(self, pcm: np.ndarray, terms: list[str], language: str | None) -> tuple[str, str | None]:
+        import mlx_whisper
+
+        prompt = "\n".join([ZH_GUARD, ", ".join(terms)]) if terms else ZH_GUARD
+        with GPU:
+            result = mlx_whisper.transcribe(
+                pcm,
+                path_or_hf_repo=self.model,
+                initial_prompt=prompt,
+                language=language or None,
+                word_timestamps=False,
+                condition_on_previous_text=False,
+                verbose=None,
+            )
+        return str(result.get("text") or "").strip(), result.get("language")
+
+
+def provider_options(model: str, terms: list[str]) -> dict[str, Any] | None:
+    """OpenRouter routes one body to many providers, and each reads the vocabulary from its own field:
+    mai-transcribe-2 ignores `prompt` and goes 59 → 68 of 82 terms with `azure.phraseList`."""
+    if model.startswith("microsoft/mai-transcribe"):
+        return {"azure": {"phraseList": {"phrases": terms}}}
+    if model.startswith("openai/gpt-4o"):
+        return {"openai": {"prompt": ", ".join(terms)}}
+    if model == "openai/whisper-large-v3":
+        return {slug: {"prompt": ", ".join(terms)} for slug in ("groq", "deepinfra/us", "together")}
+    return None  # gemini rejects a prompt outright
+
+
+def wav_bytes(pcm: np.ndarray) -> bytes:
+    out = io.BytesIO()
+    with wave.open(out, "wb") as wav:
+        wav.setnchannels(1)
+        wav.setsampwidth(2)
+        wav.setframerate(SAMPLE_RATE)
+        wav.writeframes((np.clip(pcm, -1, 1) * 32767).astype("<i2").tobytes())
+    return out.getvalue()
+
+
+class CloudASR:
+    """One OpenAI-compatible transcription endpoint. OpenRouter gets its JSON body so the
+    vocabulary reaches the provider's own field; everything else gets the standard multipart
+    form with the vocabulary as `prompt`."""
+
+    max_terms = 100
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.base = str(config.get("baseURL") or "https://openrouter.ai/api/v1").rstrip("/")
+        self.model = str(config.get("model") or "microsoft/mai-transcribe-2")
+        key = config.get("apiKey") or os.environ.get(str(config.get("apiKeyEnv") or "OPENROUTER_API_KEY"))
+        if not key:
+            raise RuntimeError("cloud backend has no API key: set apiKey or apiKeyEnv in config.json")
+        self.key = str(key)
+        self.name = f"cloud:{self.model}"
+
+    def request(self, audio: bytes, terms: list[str], language: str | None) -> urllib.request.Request:
+        url = f"{self.base}/audio/transcriptions"
+        auth = {"Authorization": f"Bearer {self.key}"}
+        if "openrouter.ai" in self.base:
+            body: dict[str, Any] = {
+                "model": self.model,
+                "input_audio": {"data": base64.b64encode(audio).decode(), "format": "wav"},
+            }
+            if language:
+                body["language"] = language
+            options = provider_options(self.model, terms) if terms else None
+            if options:
+                body["provider"] = {"options": options}
+            return urllib.request.Request(url, json.dumps(body).encode(), {**auth, "Content-Type": "application/json"})
+        fields = {"model": self.model, **({"language": language} if language else {})}
+        if terms:
+            fields["prompt"] = ", ".join(terms)
+        boundary = uuid.uuid4().hex
+        parts = [
+            f'--{boundary}\r\nContent-Disposition: form-data; name="file"; filename="audio.wav"\r\n'
+            "Content-Type: audio/wav\r\n\r\n".encode()
+            + audio
+            + b"\r\n"
+        ]
+        for name, value in fields.items():
+            parts.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"\r\n\r\n{value}\r\n'.encode())
+        parts.append(f"--{boundary}--\r\n".encode())
+        headers = {**auth, "Content-Type": f"multipart/form-data; boundary={boundary}"}
+        return urllib.request.Request(url, b"".join(parts), headers)
+
+    def transcribe(self, pcm: np.ndarray, terms: list[str], language: str | None) -> tuple[str, str | None]:
+        try:
+            with urllib.request.urlopen(self.request(wav_bytes(pcm), terms, language), timeout=CLOUD_TIMEOUT_S) as res:
+                body = json.loads(res.read())
+        except urllib.error.HTTPError as err:
+            raise RuntimeError(f"{self.name} answered {err.code}: {err.read()[:200]!r}") from err
+        return str(body.get("text") or "").strip(), body.get("language")
+
+
+def backend(config: dict[str, Any]) -> Backend:
+    if config.get("backend") == "cloud":
+        return CloudASR(config)
+    return LocalWhisper(os.environ.get("ROVE_VOICE_MODEL") or str(config.get("model") or LOCAL_MODEL))
+
+
+@cache
+def _t2s() -> Any:
+    from opencc import OpenCC
+
+    return OpenCC("t2s")
+
+
+def simplified(text: str) -> str:
+    """Whisper drifts into Traditional characters on some Mandarin clips; English passes through."""
+    return _t2s().convert(text) if any("一" <= c <= "鿿" for c in text) else text

package/dist/voice/fetch_model.py

@@ -0,0 +1,30 @@
+"""Download the local recognizer once, so the sidecar's first start does not wait on the network.
+
+Run by the bridge's install job (`rove-bridge/src/ops/voice-setup.ts`) after `uv sync --extra local`.
+Prints one progress line per file; writes `~/.rove/voice/installed.json` when the model is complete.
+A rerun resumes: the Hugging Face cache keeps what already arrived.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+
+import engine
+
+
+def main() -> None:
+    from huggingface_hub import snapshot_download
+
+    config = engine.load_config()
+    model = str(config.get("model") or engine.LOCAL_MODEL) if config.get("backend") != "cloud" else engine.LOCAL_MODEL
+    print(f"downloading {model}", flush=True)
+    path = snapshot_download(model)
+    engine.HOME.mkdir(parents=True, exist_ok=True)
+    (engine.HOME / "installed.json").write_text(json.dumps({"model": model, "path": path, "at": int(time.time())}))
+    print(f"installed {model}", flush=True)
+
+
+if __name__ == "__main__":
+    sys.exit(main())