dexterm-cli 0.1.1 → 0.1.2

package/dist/packages/tui/src/raster.js

@@ -0,0 +1,213 @@
+import { ATTR_BOLD, ATTR_DIM, ATTR_UNDERLINE } from "./canvas.js";
+import { hexToRgb, mix } from "./color.js";
+import { glyphBits, FONT_W, FONT_H } from "./raster-font.js";
+class Px {
+    w;
+    h;
+    rgba;
+    constructor(w, h) { this.w = w; this.h = h; this.rgba = new Uint8Array(w * h * 4); }
+    rect(x, y, w, h, c, a = 1) {
+        const x0 = Math.max(0, Math.floor(x)), y0 = Math.max(0, Math.floor(y));
+        const x1 = Math.min(this.w, Math.floor(x + w)), y1 = Math.min(this.h, Math.floor(y + h));
+        for (let yy = y0; yy < y1; yy++)
+            for (let xx = x0; xx < x1; xx++) {
+                const i = (yy * this.w + xx) * 4;
+                if (a >= 1) {
+                    this.rgba[i] = c[0];
+                    this.rgba[i + 1] = c[1];
+                    this.rgba[i + 2] = c[2];
+                }
+                else {
+                    this.rgba[i] = Math.round(this.rgba[i] * (1 - a) + c[0] * a);
+                    this.rgba[i + 1] = Math.round(this.rgba[i + 1] * (1 - a) + c[1] * a);
+                    this.rgba[i + 2] = Math.round(this.rgba[i + 2] * (1 - a) + c[2] * a);
+                }
+                this.rgba[i + 3] = 255;
+            }
+    }
+}
+// Box drawing: up, down, left, right weights (0 none, 1 light, 2 heavy/double) and a dashed flag.
+const BOX = {
+    '─': '0011', '━': '0022', '│': '1100', '┃': '2200',
+    '┌': '0101', '╭': '0101', '┐': '0110', '╮': '0110', '└': '1001', '╰': '1001', '┘': '1010', '╯': '1010',
+    '┏': '0202', '┓': '0220', '┗': '2002', '┛': '2020',
+    '├': '1101', '┤': '1110', '┬': '0111', '┴': '1011', '┼': '1111',
+    '┣': '2202', '┫': '2220', '┳': '0222', '┻': '2022', '╋': '2222',
+    '═': '0022', '║': '2200', '╔': '0202', '╗': '0220', '╚': '2002', '╝': '2020', '╠': '2202', '╣': '2220', '╦': '0222', '╩': '2022', '╬': '2222',
+    '╴': '0010', '╵': '1000', '╶': '0001', '╷': '0100', '╸': '0020', '╹': '2000', '╺': '0002', '╻': '0200',
+};
+const DASH_H = new Set(['┄', '┅', '┈', '┉', '╌', '╍']);
+const DASH_V = new Set(['┆', '┇', '┊', '┋', '╎', '╏']);
+const EIGHTHS_LOW = '▁▂▃▄▅▆▇█';
+const EIGHTHS_LEFT = '▏▎▍▌▋▊▉█';
+const SHADES = { '░': 0.25, '▒': 0.5, '▓': 0.75 };
+// Quadrants: TL, TR, BL, BR.
+const QUAD = {
+    '▘': [1, 0, 0, 0], '▝': [0, 1, 0, 0], '▖': [0, 0, 1, 0], '▗': [0, 0, 0, 1], '▚': [1, 0, 0, 1], '▞': [0, 1, 1, 0],
+    '▛': [1, 1, 1, 0], '▜': [1, 1, 0, 1], '▙': [1, 0, 1, 1], '▟': [0, 1, 1, 1], '▀': [1, 1, 0, 0], '▄': [0, 0, 1, 1], '▌': [1, 0, 1, 0], '▐': [0, 1, 0, 1],
+};
+/** Draw one non-text glyph procedurally. Returns false when the glyph is not one of these families. */
+function drawSpecial(p, ch, x, y, cw, chh, fg, bg, scale) {
+    const box = BOX[ch];
+    if (box) {
+        const t1 = Math.max(1, scale), t2 = Math.max(2, scale * 2);
+        const [u, d, l, r] = [...box].map(Number);
+        const cx = x + Math.floor(cw / 2), cy = y + Math.floor(chh / 2);
+        const th = (wgt) => (wgt === 2 ? t2 : t1);
+        const hT = Math.max(th(l), th(r)), vT = Math.max(th(u), th(d));
+        if (l)
+            p.rect(x, cy - Math.floor(th(l) / 2), cx - x + Math.ceil(vT / 2), th(l), fg);
+        if (r)
+            p.rect(cx - Math.floor(vT / 2), cy - Math.floor(th(r) / 2), x + cw - (cx - Math.floor(vT / 2)), th(r), fg);
+        if (u)
+            p.rect(cx - Math.floor(th(u) / 2), y, th(u), cy - y + Math.ceil(hT / 2), fg);
+        if (d)
+            p.rect(cx - Math.floor(th(d) / 2), cy - Math.floor(hT / 2), th(d), y + chh - (cy - Math.floor(hT / 2)), fg);
+        return true;
+    }
+    if (DASH_H.has(ch)) {
+        const t = Math.max(1, scale);
+        const seg = Math.max(2, Math.floor(cw / 4));
+        for (let k = 0; k < cw; k += seg * 2)
+            p.rect(x + k, y + Math.floor(chh / 2) - Math.floor(t / 2), seg, t, fg);
+        return true;
+    }
+    if (DASH_V.has(ch)) {
+        const t = Math.max(1, scale);
+        const seg = Math.max(2, Math.floor(chh / 6));
+        for (let k = 0; k < chh; k += seg * 2)
+            p.rect(x + Math.floor(cw / 2) - Math.floor(t / 2), y + k, t, seg, fg);
+        return true;
+    }
+    const low = EIGHTHS_LOW.indexOf(ch);
+    if (low >= 0) {
+        const hh = Math.round((chh * (low + 1)) / 8);
+        p.rect(x, y + chh - hh, cw, hh, fg);
+        return true;
+    }
+    const left = EIGHTHS_LEFT.indexOf(ch);
+    if (left >= 0) {
+        p.rect(x, y, Math.round((cw * (left + 1)) / 8), chh, fg);
+        return true;
+    }
+    if (ch === '▔') {
+        p.rect(x, y, cw, Math.max(1, Math.round(chh / 8)), fg);
+        return true;
+    }
+    if (ch === '▕') {
+        const ww = Math.max(1, Math.round(cw / 8));
+        p.rect(x + cw - ww, y, ww, chh, fg);
+        return true;
+    }
+    const shade = SHADES[ch];
+    if (shade !== undefined) {
+        p.rect(x, y, cw, chh, [Math.round(bg[0] + (fg[0] - bg[0]) * shade), Math.round(bg[1] + (fg[1] - bg[1]) * shade), Math.round(bg[2] + (fg[2] - bg[2]) * shade)]);
+        return true;
+    }
+    const q = QUAD[ch];
+    if (q) {
+        const hw = Math.floor(cw / 2), hh = Math.floor(chh / 2);
+        if (q[0])
+            p.rect(x, y, hw, hh, fg);
+        if (q[1])
+            p.rect(x + hw, y, cw - hw, hh, fg);
+        if (q[2])
+            p.rect(x, y + hh, hw, chh - hh, fg);
+        if (q[3])
+            p.rect(x + hw, y + hh, cw - hw, chh - hh, fg);
+        return true;
+    }
+    const code = ch.codePointAt(0) ?? 0;
+    if (code >= 0x2800 && code <= 0x28ff) {
+        const bits = code - 0x2800;
+        // dot n → (column, row): 1(0,0) 2(0,1) 3(0,2) 4(1,0) 5(1,1) 6(1,2) 7(0,3) 8(1,3)
+        const dots = [[0x01, 0, 0], [0x02, 0, 1], [0x04, 0, 2], [0x08, 1, 0], [0x10, 1, 1], [0x20, 1, 2], [0x40, 0, 3], [0x80, 1, 3]];
+        const dw = Math.max(1, Math.floor(cw / 4)), dh = Math.max(1, Math.floor(chh / 8));
+        for (const [bit, col, row] of dots)
+            if (bits & bit)
+                p.rect(x + Math.floor((cw * (col * 2 + 1)) / 4) - Math.floor(dw / 2), y + Math.floor((chh * (row * 2 + 1)) / 8) - Math.floor(dh / 2), dw, dh, fg);
+        return true;
+    }
+    if (ch === '╱' || ch === '╲' || ch === '╳') {
+        const t = Math.max(1, scale);
+        for (let k = 0; k < chh; k++) {
+            const fx = Math.floor((k * cw) / chh);
+            if (ch !== '╲')
+                p.rect(x + cw - 1 - fx - Math.floor(t / 2), y + k, t, 1, fg);
+            if (ch !== '╱')
+                p.rect(x + fx - Math.floor(t / 2), y + k, t, 1, fg);
+        }
+        return true;
+    }
+    return false;
+}
+/** Rasterize every cell of a canvas: background, glyph (font or procedural), attributes, then image slots. */
+export function rasterizeCanvas(c, opts = {}) {
+    const cw = opts.cellW ?? 12, chh = opts.cellH ?? 24, scale = opts.scale ?? 2;
+    const p = new Px(c.w * cw, c.h * chh);
+    const gx = Math.floor((cw - FONT_W * scale) / 2), gy = Math.floor((chh - FONT_H * scale) / 2);
+    const rgbCache = new Map();
+    const rgb = (h) => { let v = rgbCache.get(h); if (!v) {
+        v = hexToRgb(h);
+        rgbCache.set(h, v);
+    } return v; };
+    for (let row = 0; row < c.h; row++)
+        for (let col = 0; col < c.w; col++) {
+            const i = row * c.w + col;
+            const x = col * cw, y = row * chh;
+            const bgHex = c.bg[i];
+            const bg = rgb(bgHex);
+            p.rect(x, y, cw, chh, bg);
+            const ch = c.ch[i];
+            if (ch === ' ' || ch === '')
+                continue;
+            const at = c.at[i];
+            const fg = rgb(at & ATTR_DIM ? mix(c.fg[i], bgHex, 0.45) : c.fg[i]);
+            if (drawSpecial(p, ch, x, y, cw, chh, fg, bg, scale))
+                continue;
+            let bits = glyphBits(ch);
+            // an accented LETTER falls back to its base letter (é → e); never a digit or symbol, whose compatibility form
+            // can change meaning (a subscript ₅ is not a 5)
+            if (!bits && /^\p{L}$/u.test(ch)) {
+                const base = ch.normalize('NFD').replace(/\p{M}+/gu, '');
+                if (base && base !== ch)
+                    bits = glyphBits(base[0]);
+            }
+            if (!bits) {
+                // tofu: a hollow box so an unsupported glyph is visible, never silently dropped
+                const t = Math.max(1, Math.floor(scale / 2));
+                const bx = x + gx + scale, by = y + gy + scale * 2, bw = (FONT_W - 2) * scale, bh = (FONT_H - 4) * scale;
+                p.rect(bx, by, bw, t, fg);
+                p.rect(bx, by + bh - t, bw, t, fg);
+                p.rect(bx, by, t, bh, fg);
+                p.rect(bx + bw - t, by, t, bh, fg);
+                continue;
+            }
+            const bold = (at & ATTR_BOLD) !== 0;
+            for (let yy = 0; yy < FONT_H; yy++)
+                for (let xx = 0; xx < FONT_W; xx++) {
+                    if (!bits[yy * FONT_W + xx])
+                        continue;
+                    p.rect(x + gx + xx * scale, y + gy + yy * scale, scale + (bold ? 1 : 0), scale, fg);
+                }
+            if (at & ATTR_UNDERLINE)
+                p.rect(x, y + chh - Math.max(1, scale), cw, Math.max(1, Math.floor(scale / 2)), fg);
+        }
+    // Pixel image slots (coin images) recorded by the canvas in 'pixels' mode: nearest-neighbour into the cell rect.
+    for (const s of c.images) {
+        const rx = s.x * cw, ry = s.y * chh, rw = s.w * cw, rh = s.h * chh;
+        const { w: iw, h: ih, rgba } = s.img;
+        if (!iw || !ih)
+            continue;
+        for (let yy = 0; yy < rh; yy++)
+            for (let xx = 0; xx < rw; xx++) {
+                const sx = Math.min(iw - 1, Math.floor((xx * iw) / rw)), sy = Math.min(ih - 1, Math.floor((yy * ih) / rh));
+                const si = (sy * iw + sx) * 4;
+                const a = rgba[si + 3] / 255;
+                if (a <= 0)
+                    continue;
+                p.rect(rx + xx, ry + yy, 1, 1, [rgba[si], rgba[si + 1], rgba[si + 2]], a);
+            }
+    }
+    return { w: p.w, h: p.h, rgba: p.rgba };
+}

package/dist/packages/voice/src/controller.js

@@ -5,6 +5,7 @@
 // listen() is called — so the on-screen indicator and the real mic state can never disagree.
 import { route, isSafe } from "./router.js";
 import { spokenSummary } from "./summary.js";
+import { isBannedVoice } from "./tts/voices.js";
 export class VoiceController {
     stt;
     tts;
@@ -15,6 +16,7 @@ export class VoiceController {
     muted;
     voice;
     rate;
+    pitch;
     voices = [];
     lastTranscript = null;
     lastSay = null;
@@ -43,6 +45,7 @@ export class VoiceController {
         this.muted = opts.muted ?? false;
         this.voice = opts.voice ?? null;
         this.rate = opts.rate ?? 190;
+        this.pitch = opts.pitch;
         this.now = opts.now ?? (() => Date.now());
         this.maxListenMs = opts.maxListenMs ?? 15_000;
         this.setTimer = opts.setTimer ?? ((fn, ms) => { const h = setTimeout(fn, ms); h.unref?.(); return h; });
@@ -71,12 +74,16 @@ export class VoiceController {
     get isListening() { return this.mode === 'listening'; }
     /** The mic is live OR about to be (listen() in flight): the states a key must cancel. */
     get micEngaged() { return this.mode === 'listening' || this.starting; }
-    /** Load the voice list lazily (used by cycleVoice and the status line). */
+    /**
+     * Load the voice list lazily (used by cycleVoice and the status line). Novelty voices on the ban-list
+     * are filtered OUT so the user can never cycle into "Zarvox" / "Bad News" and so a null starting voice
+     * is seeded to a safe one, never the machine's (possibly novelty) system voice (task-1393).
+     */
     async loadVoices() {
         if (!this.tts)
             return;
         try {
-            this.voices = await this.tts.listVoices();
+            this.voices = (await this.tts.listVoices()).filter((n) => !isBannedVoice(n));
             if (!this.voice && this.voices.length)
                 this.voice = this.voices[0];
         }
@@ -285,6 +292,7 @@ export class VoiceController {
         const handle = this.tts.speak(text, {
             voice: this.voice ?? undefined,
             rate: this.rate,
+            pitch: this.pitch,
             onFirstAudio: () => this.recordFirstAudio(),
         });
         this.speaking = handle;
@@ -362,7 +370,7 @@ export class VoiceController {
         this.stopSpeaking(); this.notify(); }
     toggleMute() { this.setMuted(!this.muted); }
     get isMuted() { return this.muted; }
-    /** Cycle to the next installed voice (macOS voices). No-op when there are none. */
+    /** Cycle to the next installed (safe) voice and persist the choice. No-op when there are none. */
     cycleVoice() {
         if (!this.voices.length) {
             this.notify();
@@ -370,6 +378,10 @@ export class VoiceController {
         }
         const i = this.voice ? this.voices.indexOf(this.voice) : -1;
         this.voice = this.voices[(i + 1) % this.voices.length];
+        try {
+            this.opts.onVoiceChange?.(this.voice);
+        }
+        catch { /* persistence is best-effort; never break the UI */ }
         this.notify();
     }
     currentVoice() { return this.voice; }

package/dist/packages/voice/src/doctor.js

@@ -7,16 +7,84 @@
 export function voiceDoctor(deps) {
     const checks = [];
     if (deps.platform !== 'darwin') {
-        checks.push({
-            name: 'Voice mode', status: 'warn',
-            detail: `voice mode is macOS-only for now (speech uses the built-in \`say\` and Apple Speech); on ${deps.platform} it stays off and dexterm runs as text`,
-            fix: 'Use dexterm on macOS for voice, or just use the keyboard — every voice action has a key.',
-        });
+        const win = deps.platform === 'win32';
+        // Speech OUT off macOS: Piper (neural, preferred) → espeak-ng (baseline) → warn (task-1408).
+        // NOTE: `apt install piper` on Debian is an UNRELATED gaming-mouse tool — never suggest it; the
+        // Piper TTS binary comes from the rhasspy/piper prebuilt release, the voice from `dexterm voice download`.
+        const piperRelease = 'github.com/rhasspy/piper/releases';
+        const whisperRelease = 'github.com/ggml-org/whisper.cpp/releases';
+        const piperReady = !!deps.piperPresent && !!deps.piperVoicePresent && !!deps.playerName;
+        // What Piper is still missing (for an upgrade hint / the no-voice fix).
+        const piperBits = [];
+        if (!deps.piperPresent)
+            piperBits.push(`the Piper binary (prebuilt from ${piperRelease} into \`~/.dexterm/piper/\`, NOT \`apt install piper\`)`);
+        if (!deps.piperVoicePresent)
+            piperBits.push('the voice model (`dexterm voice download piper-voice` — asks first, checksum-verified)');
+        if (!deps.playerName)
+            piperBits.push(win ? 'an audio player (ffplay from ffmpeg)' : 'an audio player (`sudo apt install alsa-utils` for aplay, or pulseaudio-utils for paplay)');
+        if (piperReady) {
+            checks.push({ name: 'Voice out (Piper)', status: 'pass', detail: `Piper neural voice ready — en_GB-alan-medium, plays via ${deps.playerName} (local, no key)` });
+        }
+        else if (deps.espeakPresent) {
+            checks.push({
+                name: 'Voice out (espeak-ng)', status: 'pass',
+                detail: `espeak-ng ready — British male default (local, no key). For a higher-quality neural voice, add Piper: ${piperBits.join('; ')}`,
+            });
+        }
+        else {
+            checks.push({
+                name: 'Voice out', status: 'warn',
+                detail: `spoken replies are off on ${deps.platform} until a speech engine is installed; the analyst still answers in text`,
+                fix: win
+                    ? 'Install espeak-ng (`choco install espeak` or the espeak-ng release). For a neural voice, add Piper (prebuilt from '
+                        + `${piperRelease}) + \`dexterm voice download piper-voice\` + ffplay.`
+                    : 'Fastest: `sudo apt install espeak-ng`. Better (neural): install the Piper prebuilt binary from '
+                        + `${piperRelease} into \`~/.dexterm/piper/\`, run \`dexterm voice download piper-voice\`, and \`sudo apt install alsa-utils\` for a player. `
+                        + 'Do NOT `apt install piper` — on Debian that is an unrelated mouse tool.',
+            });
+        }
+        // Speech IN — whisper.cpp (the default off macOS). Not in Debian: use the prebuilt release.
+        if (deps.resolvedStt === 'whisper' || (deps.whisperBinPresent && deps.whisperModelPresent && deps.micToolPresent)) {
+            checks.push({ name: 'Voice in (whisper)', status: 'pass', detail: 'whisper.cpp base.en + a mic tool (local, no key)' });
+        }
+        else {
+            const bits = [];
+            if (!deps.whisperBinPresent)
+                bits.push('no whisper-cli');
+            else if (!deps.whisperModelPresent)
+                bits.push('no base.en model');
+            if (!deps.micToolPresent)
+                bits.push('no mic tool (arecord/sox/ffmpeg)');
+            checks.push({
+                name: 'Voice in', status: 'warn',
+                detail: `speech-to-text is off (${bits.join(', ') || 'whisper not set up'}); you can still type questions — voice degrades to text`,
+                fix: `Install whisper.cpp (not in Debian — use the prebuilt release from ${whisperRelease}) + a mic tool `
+                    + '(`sudo apt install alsa-utils` for arecord, or sox), then `dexterm voice download whisper` (asks first, checksum-verified).',
+            });
+        }
+        if (win) {
+            checks.push({
+                name: 'Windows voice', status: 'warn',
+                detail: 'espeak-ng (or Piper) is the supported Windows speech-out path; native SAPI is not wired in this build',
+                fix: 'Use espeak-ng or Piper on Windows for now. (SAPI support is a later enhancement.)',
+            });
+        }
         return checks;
     }
     // Speech OUT — macOS say.
     if (deps.sayAvailable) {
         checks.push({ name: 'Voice out (say)', status: 'pass', detail: `macOS \`say\` ready · ${deps.voiceCount} voice${deps.voiceCount === 1 ? '' : 's'} (press the voice key, then cycle the voice)` });
+        // Which voice speaks, and why — so a machine can never silently use a novelty/odd system voice (task-1393).
+        if (deps.resolvedVoice) {
+            checks.push({ name: 'Default voice', status: 'pass', detail: `${deps.resolvedVoiceReason ?? deps.resolvedVoice} · , changes it` });
+        }
+        else if (deps.resolvedVoice === null) {
+            checks.push({
+                name: 'Default voice', status: 'warn',
+                detail: deps.resolvedVoiceReason ?? 'no safe voice installed — spoken replies are off (text still works)',
+                fix: 'Install a British male voice in System Settings → Accessibility → Spoken Content → System Voice → Manage Voices (Daniel, English (UK)); the Enhanced/Premium download sounds best.',
+            });
+        }
     }
     else {
         checks.push({
@@ -47,8 +115,8 @@ export function voiceDoctor(deps) {
             name: 'Voice in', status: 'warn',
             detail: `speech-to-text is off (${bits.join(', ')}); you can still type questions — voice degrades to text`,
             fix: 'Fastest free path: install Xcode command line tools for Apple Speech (`xcode-select --install`). '
-                + 'Or whisper: `brew install whisper-cpp sox`, then download base.en to '
-                + '`~/.dexterm/models/ggml-base.en.bin` (from the whisper.cpp model repo). Never use large-v3-turbo on a CPU-only Mac — it is unusably slow.',
+                + 'Or whisper: `brew install whisper-cpp sox`, then `dexterm voice download whisper` (asks first, checksum-verified, writes '
+                + '`~/.dexterm/models/ggml-base.en.bin`). Never use large-v3-turbo on a CPU-only Mac — it is unusably slow.',
         });
     }
     // Mic-capture tool note (only relevant to the whisper path; Apple Speech captures its own audio).

package/dist/packages/voice/src/download.js

@@ -0,0 +1,184 @@
+// Voice model downloader (task-1408). The whisper.cpp base.en model and the Piper en_GB-alan-medium
+// voice are NOT shipped (free-forever rule: no bundled large binaries, no keys). dexterm downloads them
+// on request, and ONLY on request:
+//   - from the OFFICIAL source (the ggml-org / rhasspy repositories on Hugging Face),
+//   - after EXPLICIT user confirmation (never a silent auto-download),
+//   - and verified against a checksum pinned here from the upstream LFS pointer, so a corrupted or
+//     tampered download is rejected and never written into place.
+//
+// This module is pure logic + injected fetch/confirm/log, so it is unit-testable with a fake registry
+// and never touches the real network in tests. The CLI (`dexterm voice download …`) wires the real
+// global fetch, a readline y/N prompt, and stdout.
+import { createHash } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdir, rename, rm, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { Readable } from 'node:stream';
+import { once } from 'node:events';
+/** Total download size of a spec, in whole MB (for the prompt). */
+export function specSizeMB(spec) {
+    return Math.round(spec.files.reduce((n, f) => n + (f.size ?? 0), 0) / (1024 * 1024));
+}
+/**
+ * The downloadable voice models, keyed by id. `home` is the dexterm home (~/.dexterm) so tests can
+ * point it at a temp dir. Checksums are pinned from the upstream Hugging Face LFS pointers (verified
+ * 2026-10-16): ggerganov/whisper.cpp and rhasspy/piper-voices@v1.0.0.
+ */
+export function modelRegistry(home = join(homedir(), '.dexterm')) {
+    const models = join(home, 'models');
+    return {
+        whisper: {
+            id: 'whisper',
+            label: 'whisper.cpp base.en (speech-to-text)',
+            note: 'whisper.cpp base.en — on-device speech recognition, ~141 MB, MIT (ggml-org/whisper.cpp)',
+            files: [{
+                    url: 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin',
+                    dest: join(models, 'ggml-base.en.bin'),
+                    sha256: 'a03779c86df3323075f5e796cb2ce5029f00ec8869eee3fdfb897afe36c6d002',
+                    size: 147964211,
+                }],
+        },
+        'piper-voice': {
+            id: 'piper-voice',
+            label: 'Piper en_GB-alan-medium (neural voice)',
+            note: 'Piper en_GB-alan-medium — British male neural voice, ~61 MB, MIT (rhasspy/piper-voices)',
+            files: [
+                {
+                    url: 'https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_GB/alan/medium/en_GB-alan-medium.onnx',
+                    dest: join(models, 'en_GB-alan-medium.onnx'),
+                    sha256: '0a309668932205e762801f1efc2736cd4b0120329622adf62be09e56339d3330',
+                    size: 63201294,
+                },
+                {
+                    url: 'https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_GB/alan/medium/en_GB-alan-medium.onnx.json',
+                    dest: join(models, 'en_GB-alan-medium.onnx.json'),
+                    validateJson: true,
+                },
+            ],
+        },
+    };
+}
+/** sha256 of an existing file, or null if it cannot be read. */
+async function fileSha256(path) {
+    try {
+        const h = createHash('sha256');
+        h.update(await readFile(path));
+        return h.digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `file` is already present AND valid (checksum match, or parses as JSON for config files). */
+async function isPresentAndValid(file) {
+    if (!existsSync(file.dest))
+        return false;
+    if (file.validateJson) {
+        try {
+            JSON.parse(await readFile(file.dest, 'utf8'));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (file.sha256)
+        return (await fileSha256(file.dest)) === file.sha256.toLowerCase();
+    return true;
+}
+/**
+ * Download and verify one file. Streams to a `.part` temp alongside the destination (bounded memory),
+ * verifies size + sha256 (or JSON), then atomically renames into place. On ANY failure the temp is
+ * removed and nothing is written to the destination.
+ */
+async function downloadFile(file, fetchImpl, log) {
+    await mkdir(dirname(file.dest), { recursive: true });
+    const tmp = `${file.dest}.part`;
+    await rm(tmp, { force: true });
+    log(`  ↓ ${file.url}`);
+    let res;
+    try {
+        res = await fetchImpl(file.url, { redirect: 'follow' });
+    }
+    catch (e) {
+        throw new Error(`download failed (${file.url}): ${e.message}`);
+    }
+    if (!res.ok || !res.body)
+        throw new Error(`download failed (${file.url}): HTTP ${res.status}`);
+    const hash = createHash('sha256');
+    const out = createWriteStream(tmp);
+    let bytes = 0;
+    try {
+        for await (const chunk of Readable.fromWeb(res.body)) {
+            const buf = chunk;
+            bytes += buf.length;
+            hash.update(buf);
+            if (!out.write(buf))
+                await once(out, 'drain');
+        }
+        out.end();
+        await once(out, 'finish');
+    }
+    catch (e) {
+        out.destroy();
+        await rm(tmp, { force: true });
+        throw new Error(`download failed (${file.url}): ${e.message}`);
+    }
+    // Verify before anything lands at the real path.
+    try {
+        if (file.size !== undefined && bytes !== file.size) {
+            throw new Error(`size mismatch: got ${bytes} bytes, expected ${file.size}`);
+        }
+        if (file.sha256) {
+            const got = hash.digest('hex');
+            if (got !== file.sha256.toLowerCase())
+                throw new Error(`checksum mismatch: got ${got}, expected ${file.sha256}`);
+        }
+        else if (file.validateJson) {
+            JSON.parse(await readFile(tmp, 'utf8'));
+        }
+    }
+    catch (e) {
+        await rm(tmp, { force: true });
+        throw new Error(`verification failed (${file.url}): ${e.message}`);
+    }
+    await rename(tmp, file.dest);
+    const mb = (bytes / (1024 * 1024)).toFixed(1);
+    log(`  ✓ ${file.dest} (${mb} MB${file.sha256 ? ', sha256 ok' : ', json ok'})`);
+}
+/**
+ * Download a model after explicit confirmation. If every file is already present and valid, returns
+ * `already` WITHOUT prompting or touching the network. Otherwise it builds a one-prompt summary of what
+ * will be fetched and where, calls `confirm()`, and only then downloads + verifies each missing file.
+ */
+export async function downloadModel(spec, deps) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const log = deps.log ?? (() => { });
+    const presence = await Promise.all(spec.files.map(isPresentAndValid));
+    const missing = spec.files.filter((_, i) => !presence[i]);
+    if (missing.length === 0) {
+        log(`${spec.label} is already installed and verified.`);
+        return { status: 'already', files: spec.files.map((f) => f.dest) };
+    }
+    const dir = dirname(spec.files[0].dest);
+    const prompt = [
+        `Download ${spec.note}`,
+        `  from the official source to ${dir}`,
+        `  ${missing.length} file${missing.length === 1 ? '' : 's'}, ~${specSizeMB(spec)} MB, checksum-verified. Proceed?`,
+    ].join('\n');
+    if (!(await deps.confirm(prompt))) {
+        log('Cancelled — nothing downloaded.');
+        return { status: 'cancelled', files: spec.files.filter((_, i) => presence[i]).map((f) => f.dest) };
+    }
+    for (const f of missing)
+        await downloadFile(f, fetchImpl, log);
+    log(`${spec.label} installed.`);
+    return { status: 'ok', files: spec.files.map((f) => f.dest) };
+}
+/** Which model files exist and verify right now (for a status report; never touches the network). */
+export async function modelStatus(spec) {
+    const files = await Promise.all(spec.files.map(async (f) => ({ dest: f.dest, ok: await isPresentAndValid(f) })));
+    return { installed: files.every((f) => f.ok), files };
+}

package/dist/packages/voice/src/engines.js

@@ -5,7 +5,10 @@ import { AppleStt } from "./stt/apple.js";
 import { WhisperStt } from "./stt/whisper.js";
 import { FakeStt } from "./stt/fake.js";
 import { SayTts } from "./tts/say.js";
+import { EspeakTts, espeakVoiceFor } from "./tts/espeak.js";
+import { PiperTts } from "./tts/piper.js";
 import { FakeTts } from "./tts/fake.js";
+import { resolveVoice } from "./tts/voices.js";
 /**
  * Resolve the STT engine. `auto` prefers Apple Speech (on-device, streaming), then whisper base.en,
  * then none. An explicit choice is returned even if it later proves unavailable, so the doctor and the
@@ -29,16 +32,53 @@ export async function selectStt(choice = process.env.DEXTERM_VOICE_STT || 'auto'
         return whisper;
     return null;
 }
-/** Resolve the TTS engine. `auto` uses macOS `say` when present, else none (voice replies off). */
-export async function selectTts(choice = process.env.DEXTERM_VOICE_TTS || 'auto', defaultVoice) {
+/**
+ * Resolve the default `say` voice for this machine: the user's configured voice if it is installed and
+ * safe, else a deep British male (Daniel first), never a novelty voice and never the OS system default.
+ * Returns the full resolution (voice + why) so the controller and `dexterm doctor` can show it.
+ */
+export async function resolveSayVoice(say, configured) {
+    const installed = await say.listVoicesDetailed();
+    return resolveVoice({ configured, installed });
+}
+/**
+ * Resolve the TTS engine. `auto` uses macOS `say` when present, else none (voice replies off). When
+ * `say` is chosen, its default voice is resolved to an explicit deep British male so it can NEVER fall
+ * back to the machine's system voice (task-1393). `configuredVoice` is the user's `config.voice.name`.
+ */
+export async function selectTts(choice = process.env.DEXTERM_VOICE_TTS || 'auto', configuredVoice) {
     if (choice === 'none')
         return null;
     if (choice === 'fake')
         return new FakeTts();
-    if (choice === 'say')
-        return new SayTts(defaultVoice);
-    const say = new SayTts(defaultVoice);
-    if (await say.available())
-        return say;
-    return null;
+    // Piper and espeak are the off-macOS engines. A macOS voice name (config.voice.name is e.g.
+    // "Eddy (English (UK))") is NEVER passed to them verbatim: Piper's voice is its model, and espeak
+    // only honours a real espeak voice token (espeakVoiceFor drops a Mac name → the British default).
+    if (choice === 'piper') {
+        const p = new PiperTts();
+        return (await p.available()) ? p : null;
+    }
+    if (choice === 'espeak') {
+        const e = new EspeakTts(espeakVoiceFor(configuredVoice) ?? undefined);
+        return (await e.available()) ? e : null;
+    }
+    // On macOS, prefer `say`. Off macOS, `say` does not exist — use the portable engines below.
+    if (choice === 'say' || (choice === 'auto' && process.platform === 'darwin')) {
+        const probe = new SayTts();
+        if (choice === 'auto' && !(await probe.available()))
+            return null;
+        const r = await resolveSayVoice(probe, configuredVoice);
+        // No safe voice installed (only novelty voices): voice-out stays OFF so `say` can never be invoked
+        // without an explicit voice and fall back to the machine's system voice (task-1393). Text still works.
+        if (r.voice === null)
+            return null;
+        return new SayTts(r.voice);
+    }
+    // auto, non-darwin: Piper (neural, higher quality) when it can speak aloud, else espeak-ng, else
+    // text-only. Neither engine is ever handed a macOS voice name (task-1408).
+    const piper = new PiperTts();
+    if (await piper.available())
+        return piper;
+    const espeak = new EspeakTts(espeakVoiceFor(configuredVoice) ?? undefined);
+    return (await espeak.available()) ? espeak : null;
 }

package/dist/packages/voice/src/index.js

@@ -7,10 +7,14 @@ export * from "./types.js";
 export { route, isSafe } from "./router.js";
 export { spokenSummary, splitSentences } from "./summary.js";
 export { VoiceController } from "./controller.js";
-export { selectStt, selectTts } from "./engines.js";
+export { selectStt, selectTts, resolveSayVoice } from "./engines.js";
 export { voiceDoctor } from "./doctor.js";
-export { SayTts } from "./tts/say.js";
+export { resolveVoice, isBannedVoice, normalizeVoiceName, parseSayVoices, sanitizeSpeech, BANNED_VOICE_NAMES, BRITISH_MALE_PREFERENCE, MAX_SPEAK_CHARS, VOICE_STYLE_DEFAULTS, voiceStyleDefaults, } from "./tts/voices.js";
+export { SayTts, DEFAULT_RATE } from "./tts/say.js";
+export { EspeakTts, DEFAULT_ESPEAK_VOICE, resolveEspeakBin, espeakVoiceFor } from "./tts/espeak.js";
+export { PiperTts, DEFAULT_PIPER_VOICE, PIPER_MODEL, PIPER_PLAYERS, resolvePiperBin, pickPlayer } from "./tts/piper.js";
 export { FakeTts } from "./tts/fake.js";
-export { WhisperStt, WHISPER_MODEL, WHISPER_MODEL_DIR } from "./stt/whisper.js";
+export { WhisperStt, WHISPER_MODEL, WHISPER_MODEL_DIR, pickRecorder } from "./stt/whisper.js";
+export { modelRegistry, downloadModel, modelStatus, specSizeMB, } from "./download.js";
 export { AppleStt, ensureHelper } from "./stt/apple.js";
 export { FakeStt } from "./stt/fake.js";