@moxxy/plugin-stt-local 0.28.0

package/src/decode.ts

@@ -0,0 +1,74 @@
+/**
+ * The single entry point that turns whatever audio a caller hands the local
+ * Whisper transcriber into the Float32 mono @ 16 kHz that sherpa wants. It
+ * dispatches on the MIME type (with a RIFF magic sniff as a backstop):
+ *
+ *   - `MOXXY_PCM16_24KHZ_MIME` (the TUI/desktop mic) → int16→float32, then
+ *     linear-resample 24 kHz → 16 kHz. Never touches ffmpeg.
+ *   - `audio/wav` / `audio/x-wav`, or any buffer whose bytes start with the WAV
+ *     magic → parse the RIFF header (PCM16 only), downmix, resample. No ffmpeg.
+ *   - everything else (ogg/opus, mp3, m4a, webm, flac, …) → ffmpeg.
+ *
+ * The MIME string is UNTRUSTED (channels forward a messenger's `mime_type`
+ * verbatim), so it's runtime-guarded and canonicalized before matching.
+ */
+
+import { MOXXY_PCM16_24KHZ_MIME } from '@moxxy/sdk';
+import type { spawn } from 'node:child_process';
+
+import {
+  downmixToMono,
+  isRiffWave,
+  parseWav,
+  pcm16ToFloat32,
+  resampleLinear,
+  TARGET_SAMPLE_RATE,
+} from './audio.js';
+import { decodeViaFfmpeg } from './ffmpeg.js';
+
+/** The raw mic contract carries mono int16 @ this rate (see the SDK MIME tag). */
+const MOXXY_PCM16_SAMPLE_RATE = 24_000;
+
+export interface DecodeOptions {
+  /** Injected `spawn` for the ffmpeg path (tests). Defaults to real `spawn`. */
+  readonly spawnImpl?: typeof spawn;
+}
+
+/**
+ * Decode `audio` to Float32 mono PCM in [-1, 1] at 16 kHz. Throws a MoxxyError
+ * for malformed WAV (non-PCM16) or when ffmpeg is needed but missing.
+ */
+export async function decodeToMono16k(
+  audio: Uint8Array | ArrayBuffer,
+  mimeType: string | undefined,
+  opts: DecodeOptions = {},
+): Promise<Float32Array> {
+  const bytes = audio instanceof Uint8Array ? audio : new Uint8Array(audio);
+  const mt = canonicalMime(mimeType);
+
+  // 1) Raw PCM16 mono @ 24 kHz from the moxxy mic recorder.
+  if (mt === MOXXY_PCM16_24KHZ_MIME) {
+    const mono = pcm16ToFloat32(bytes);
+    return resampleLinear(mono, MOXXY_PCM16_SAMPLE_RATE, TARGET_SAMPLE_RATE);
+  }
+
+  // 2) WAV — by declared MIME or by sniffing the RIFF/WAVE magic (a mislabelled
+  //    or MIME-less WAV still decodes in-process).
+  if (mt === 'audio/wav' || mt === 'audio/x-wav' || mt === 'audio/wave' || isRiffWave(bytes)) {
+    const wav = parseWav(bytes);
+    const mono = wav.channels > 1 ? downmixToMono(wav.samples, wav.channels) : wav.samples;
+    return wav.sampleRate === TARGET_SAMPLE_RATE
+      ? mono
+      : resampleLinear(mono, wav.sampleRate, TARGET_SAMPLE_RATE);
+  }
+
+  // 3) Everything else is a compressed container → ffmpeg (already resamples to
+  //    16 kHz mono for us).
+  return decodeViaFfmpeg(bytes, opts.spawnImpl);
+}
+
+/** Lower-case, strip a `; codecs=…` parameter, trim. Non-string → ''. */
+function canonicalMime(mimeType: string | undefined): string {
+  const raw = typeof mimeType === 'string' ? mimeType : '';
+  return raw.toLowerCase().split(';')[0]!.trim();
+}

package/src/ffmpeg.test.ts

@@ -0,0 +1,142 @@
+import { Buffer } from 'node:buffer';
+import { EventEmitter } from 'node:events';
+import type { spawn } from 'node:child_process';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { __resetFfmpegProbeForTest, decodeViaFfmpeg, missingFfmpegError } from './ffmpeg.js';
+
+/** A fake `spawn` that plays the ffmpeg probe (`-version`) and the decode
+ *  (`f32le` pipe) roles. Configurable per-role so tests drive deterministic
+ *  outcomes without a real ffmpeg. */
+interface FakeSpawnConfig {
+  /** Probe: 'ok' → exit 0, 'fail' → exit 1, 'enoent' → emit spawn error. */
+  readonly probe?: 'ok' | 'fail' | 'enoent';
+  /** Decode stdout samples (encoded as f32le), or null to emit none. */
+  readonly decodeSamples?: Float32Array | null;
+  /** Decode exit code (default 0). */
+  readonly decodeExit?: number;
+  /** Decode stderr text. */
+  readonly decodeStderr?: string;
+}
+
+function makeFakeSpawn(config: FakeSpawnConfig): {
+  spawnImpl: typeof spawn;
+  probeCalls: number;
+  decodeCalls: number;
+  fedStdin: Buffer[];
+} {
+  const stats = { probeCalls: 0, decodeCalls: 0, fedStdin: [] as Buffer[] };
+
+  const spawnImpl = ((_cmd: string, args: readonly string[]) => {
+    const child = new EventEmitter() as EventEmitter & {
+      stdout: EventEmitter;
+      stderr: EventEmitter;
+      stdin: { writable: boolean; on: () => void; end: (b?: Buffer) => void };
+      kill: () => boolean;
+      killed: boolean;
+    };
+    child.stdout = new EventEmitter();
+    child.stderr = new EventEmitter();
+    child.killed = false;
+    child.kill = () => {
+      child.killed = true;
+      return true;
+    };
+    const isProbe = args.includes('-version');
+    child.stdin = {
+      writable: true,
+      on: () => {},
+      end: (b?: Buffer) => {
+        if (b) stats.fedStdin.push(b);
+      },
+    };
+
+    if (isProbe) {
+      stats.probeCalls += 1;
+      setImmediate(() => {
+        if (config.probe === 'enoent') {
+          const err = Object.assign(new Error('spawn ffmpeg ENOENT'), { code: 'ENOENT' });
+          child.emit('error', err);
+          return;
+        }
+        child.emit('close', config.probe === 'fail' ? 1 : 0);
+      });
+      return child;
+    }
+
+    stats.decodeCalls += 1;
+    setImmediate(() => {
+      if (config.decodeStderr) child.stderr.emit('data', Buffer.from(config.decodeStderr));
+      const samples = config.decodeSamples;
+      if (samples && samples.length > 0) {
+        child.stdout.emit('data', Buffer.from(samples.buffer.slice(0)));
+      }
+      child.emit('close', config.decodeExit ?? 0);
+    });
+    return child;
+  }) as unknown as typeof spawn;
+
+  return {
+    spawnImpl,
+    get probeCalls() {
+      return stats.probeCalls;
+    },
+    get decodeCalls() {
+      return stats.decodeCalls;
+    },
+    get fedStdin() {
+      return stats.fedStdin;
+    },
+  };
+}
+
+afterEach(() => __resetFfmpegProbeForTest());
+
+describe('decodeViaFfmpeg', () => {
+  it('decodes to Float32 samples via ffmpeg, feeding the input on stdin', async () => {
+    const expected = Float32Array.from([0, 0.25, -0.5, 0.999]);
+    const fake = makeFakeSpawn({ probe: 'ok', decodeSamples: expected });
+    const input = new Uint8Array([1, 2, 3, 4]);
+    const out = await decodeViaFfmpeg(input, fake.spawnImpl);
+    expect(Array.from(out)).toEqual(Array.from(expected));
+    expect(fake.probeCalls).toBe(1);
+    expect(fake.decodeCalls).toBe(1);
+    expect(fake.fedStdin[0]!.equals(Buffer.from(input))).toBe(true);
+  });
+
+  it('throws a clear PLUGIN_LOAD_FAILED error with an install hint when ffmpeg is missing', async () => {
+    const fake = makeFakeSpawn({ probe: 'enoent' });
+    await expect(decodeViaFfmpeg(new Uint8Array([1]), fake.spawnImpl)).rejects.toMatchObject({
+      code: 'PLUGIN_LOAD_FAILED',
+    });
+    expect(fake.decodeCalls).toBe(0); // never attempted the decode
+  });
+
+  it('surfaces a non-zero ffmpeg exit as an INTERNAL error carrying stderr', async () => {
+    const fake = makeFakeSpawn({
+      probe: 'ok',
+      decodeSamples: null,
+      decodeExit: 1,
+      decodeStderr: 'Invalid data found when processing input',
+    });
+    await expect(decodeViaFfmpeg(new Uint8Array([9]), fake.spawnImpl)).rejects.toMatchObject({
+      code: 'INTERNAL',
+    });
+  });
+
+  it('errors when ffmpeg exits 0 but produces no audio', async () => {
+    const fake = makeFakeSpawn({ probe: 'ok', decodeSamples: null, decodeExit: 0 });
+    await expect(decodeViaFfmpeg(new Uint8Array([9]), fake.spawnImpl)).rejects.toThrow(
+      /produced no audio/,
+    );
+  });
+});
+
+describe('missingFfmpegError', () => {
+  it('is a PLUGIN_LOAD_FAILED MoxxyError naming ffmpeg and an install command', () => {
+    const err = missingFfmpegError();
+    expect(err.code).toBe('PLUGIN_LOAD_FAILED');
+    expect(err.message).toMatch(/ffmpeg/i);
+    expect(err.hint).toMatch(/install/i);
+  });
+});

package/src/ffmpeg.ts

@@ -0,0 +1,215 @@
+/**
+ * The ffmpeg fallback for compressed audio (ogg/opus voice notes, mp3, m4a,
+ * webm, …) that we can't decode in-process. ffmpeg reads the container on stdin
+ * and writes raw 32-bit-float mono PCM at 16 kHz to stdout, which we read
+ * straight into a Float32Array — no intermediate WAV, no temp files.
+ *
+ * Gated behind a presence probe (mirrors channel-kit's voice-reply, cached per
+ * process; an injected `spawnImpl` bypasses the cache so tests are
+ * deterministic). When ffmpeg is absent we throw a clear, actionable MoxxyError
+ * — raw PCM16 and PCM16 WAV keep working without it, only compressed input
+ * needs it.
+ */
+
+import { Buffer } from 'node:buffer';
+import { spawn } from 'node:child_process';
+
+import { getInstallHint, MoxxyError } from '@moxxy/sdk';
+
+import { TARGET_SAMPLE_RATE } from './audio.js';
+
+/** ffmpeg args: decode any input container → f32le mono @ 16 kHz on stdout. */
+const DECODE_ARGS = [
+  '-hide_banner',
+  '-loglevel',
+  'error',
+  '-i',
+  'pipe:0',
+  '-f',
+  'f32le',
+  '-ac',
+  '1',
+  '-ar',
+  String(TARGET_SAMPLE_RATE),
+  'pipe:1',
+];
+
+/** Ceiling on decoded PCM we buffer. At 16 kHz f32 mono (64 KB/s) this is ~30
+ *  minutes — well past any voice note, and bounds an adversarial input. */
+const MAX_DECODED_BYTES = 120 * 1024 * 1024;
+
+const PROBE_TIMEOUT_MS = 1_500;
+const DECODE_TIMEOUT_MS = 60_000;
+
+/**
+ * Decode compressed audio bytes to Float32 mono @ 16 kHz via ffmpeg. Throws a
+ * `PLUGIN_LOAD_FAILED` MoxxyError (with an OS-specific install hint) when ffmpeg
+ * isn't on PATH, and an `INTERNAL` MoxxyError when ffmpeg runs but fails.
+ */
+export async function decodeViaFfmpeg(
+  audio: Uint8Array,
+  spawnImpl?: typeof spawn,
+): Promise<Float32Array> {
+  const available = await probeFfmpeg(spawnImpl);
+  if (!available) throw missingFfmpegError();
+  const raw = await runDecode(audio, spawnImpl ?? spawn);
+  return f32leToFloat32(raw);
+}
+
+/** The user-facing error raised when compressed audio arrives but ffmpeg is
+ *  absent. Exported so the decode orchestrator / tests can assert on it. */
+export function missingFfmpegError(): MoxxyError {
+  const hint = getInstallHint('ffmpeg');
+  return new MoxxyError({
+    code: 'PLUGIN_LOAD_FAILED',
+    message:
+      'Local Whisper needs ffmpeg to decode compressed audio (ogg/opus, mp3, m4a, webm). Raw PCM and 16-bit PCM WAV transcribe without it.',
+    hint: `Install ffmpeg via ${hint.manager}: \`${hint.command}\`.`,
+  });
+}
+
+// Process-cached ffmpeg availability (the probe spawns a subprocess; caching
+// keeps a chatty voice channel from re-probing on every note). An injected
+// `spawnImpl` (tests) bypasses the cache.
+let ffmpegAvailable: Promise<boolean> | null = null;
+
+async function probeFfmpeg(spawnImpl?: typeof spawn): Promise<boolean> {
+  if (spawnImpl) return runProbe(spawnImpl);
+  ffmpegAvailable ??= runProbe(spawn);
+  return ffmpegAvailable;
+}
+
+/** Reset the cached ffmpeg probe (tests only). */
+export function __resetFfmpegProbeForTest(): void {
+  ffmpegAvailable = null;
+}
+
+function runProbe(spawnImpl: typeof spawn, command = 'ffmpeg'): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v: boolean): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(v);
+    };
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawnImpl(command, ['-version'], { stdio: ['ignore', 'ignore', 'ignore'] });
+    } catch {
+      resolve(false);
+      return;
+    }
+    const timer = setTimeout(() => {
+      try {
+        if (!child.killed) child.kill('SIGKILL');
+      } catch {
+        /* ignore */
+      }
+      done(false);
+    }, PROBE_TIMEOUT_MS);
+    timer.unref?.();
+    child.once('error', () => done(false));
+    child.once('close', (code) => done(code === 0));
+  });
+}
+
+function runDecode(audio: Uint8Array, spawnImpl: typeof spawn, command = 'ffmpeg'): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawnImpl(command, DECODE_ARGS, { stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (err) {
+      reject(decodeFailure(err instanceof Error ? err.message : String(err)));
+      return;
+    }
+    const out: Buffer[] = [];
+    const errChunks: Buffer[] = [];
+    let outBytes = 0;
+    let over = false;
+    let settled = false;
+    const finish = (fn: () => void): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn();
+    };
+    const timer = setTimeout(() => {
+      try {
+        if (!child.killed) child.kill('SIGKILL');
+      } catch {
+        /* ignore */
+      }
+      finish(() => reject(decodeFailure('ffmpeg decode timed out')));
+    }, DECODE_TIMEOUT_MS);
+    timer.unref?.();
+
+    child.stdout?.on('data', (c: Buffer) => {
+      if (over) return;
+      if (outBytes + c.byteLength > MAX_DECODED_BYTES) {
+        over = true;
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          /* ignore */
+        }
+        finish(() => reject(decodeFailure('decoded audio exceeded the size limit')));
+        return;
+      }
+      outBytes += c.byteLength;
+      out.push(Buffer.from(c));
+    });
+    child.stderr?.on('data', (c: Buffer) => {
+      errChunks.push(Buffer.from(c));
+      while (Buffer.concat(errChunks).byteLength > 4_096) errChunks.shift();
+    });
+    child.once('error', (err) =>
+      finish(() => reject(decodeFailure(err instanceof Error ? err.message : String(err)))),
+    );
+    child.once('close', (code) =>
+      finish(() => {
+        if (over) return; // already rejected on the size cap
+        if (code === 0 && out.length > 0) {
+          resolve(Buffer.concat(out));
+        } else if (code === 0) {
+          reject(decodeFailure('ffmpeg produced no audio'));
+        } else {
+          reject(
+            decodeFailure(`ffmpeg exited ${code}: ${Buffer.concat(errChunks).toString('utf8').trim()}`),
+          );
+        }
+      }),
+    );
+
+    const stdin = child.stdin;
+    if (stdin) {
+      stdin.on('error', () => {
+        // EPIPE if ffmpeg died before consuming stdin — the close/error handler
+        // reports the real failure; swallow this to avoid an unhandled 'error'.
+      });
+      try {
+        stdin.end(Buffer.from(audio));
+      } catch {
+        /* the close/error path reports it */
+      }
+    }
+  });
+}
+
+/** Reinterpret little-endian float32 bytes as a Float32Array. Copies through a
+ *  DataView so a non-4-aligned Buffer offset and big-endian hosts both work. */
+function f32leToFloat32(buf: Buffer): Float32Array {
+  const usable = buf.byteLength - (buf.byteLength % 4);
+  const count = usable / 4;
+  const out = new Float32Array(count);
+  const view = new DataView(buf.buffer, buf.byteOffset, usable);
+  for (let i = 0; i < count; i += 1) out[i] = view.getFloat32(i * 4, true);
+  return out;
+}
+
+function decodeFailure(detail: string): MoxxyError {
+  return new MoxxyError({
+    code: 'INTERNAL',
+    message: `Local Whisper failed to decode audio with ffmpeg: ${detail}`,
+  });
+}

package/src/host-client.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it } from 'vitest';
+import { HostClient, type ChildHandle, type ForkLike } from './host-client.js';
+import type { HostReply, HostRequest } from './host-protocol.js';
+
+/** A controllable fake sidecar: records sent requests + kill, and lets the test
+ *  drive `message`/`exit`/`error` back to the client. */
+class FakeChild implements ChildHandle {
+  readonly sent: HostRequest[] = [];
+  killed = false;
+  private readonly listeners: Record<string, Array<(...a: unknown[]) => void>> = {
+    message: [],
+    exit: [],
+    error: [],
+  };
+
+  send(message: unknown): boolean {
+    this.sent.push(message as HostRequest);
+    return true;
+  }
+  on(event: string, listener: (...args: unknown[]) => void): this {
+    this.listeners[event]!.push(listener);
+    return this;
+  }
+  kill(): boolean {
+    this.killed = true;
+    return true;
+  }
+
+  private emit(event: string, ...args: unknown[]): void {
+    for (const cb of [...this.listeners[event]!]) cb(...args);
+  }
+  /** Reply to the last request the client sent. */
+  replyOk(text: string, language?: string): void {
+    this.replyOkTo(this.sent.at(-1)!.id, text, language);
+  }
+  /** Reply to a specific request id (drives out-of-order correlation tests). */
+  replyOkTo(id: number, text: string, language?: string): void {
+    const reply: HostReply =
+      language !== undefined ? { id, ok: true, text, language } : { id, ok: true, text };
+    this.emit('message', reply);
+  }
+  replyErr(kind: 'init' | 'runtime', message: string): void {
+    const id = this.sent.at(-1)!.id;
+    this.emit('message', { id, ok: false, error: { kind, message } } satisfies HostReply);
+  }
+  crash(code = 1): void {
+    this.emit('exit', code, null);
+  }
+  errorOut(message: string): void {
+    this.emit('error', new Error(message));
+  }
+}
+
+/** A fork factory handing out a fixed list of children, tracking call count. */
+function forkFactory(children: FakeChild[]): { fork: ForkLike; calls: () => number } {
+  let n = 0;
+  const fork: ForkLike = () => {
+    const child = children[n];
+    n += 1;
+    if (!child) throw new Error(`unexpected fork #${n}`);
+    return child;
+  };
+  return { fork, calls: () => n };
+}
+
+const REQ = {
+  modelKey: '/m/base-encoder.onnx',
+  encoder: '/m/base-encoder.onnx',
+  decoder: '/m/base-decoder.onnx',
+  tokens: '/m/base-tokens.txt',
+  numThreads: 2,
+  provider: 'cpu',
+  language: '',
+  task: 'transcribe',
+  samples: new Float32Array([0.1, -0.1]),
+  sampleRate: 16_000,
+};
+
+const tick = (): Promise<void> => new Promise((r) => setTimeout(r, 0));
+
+describe('HostClient', () => {
+  it('does not fork until the first transcribe (lazy spawn)', async () => {
+    const child = new FakeChild();
+    const { fork, calls } = forkFactory([child]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+    expect(calls()).toBe(0);
+    const p = host.transcribe(REQ);
+    await tick();
+    expect(calls()).toBe(1);
+    child.replyOk('hello', 'en');
+    await expect(p).resolves.toEqual({ text: 'hello', language: 'en' });
+    host.shutdown();
+  });
+
+  it('resolves text-only replies without a language field', async () => {
+    const child = new FakeChild();
+    const { fork } = forkFactory([child]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+    const p = host.transcribe(REQ);
+    await tick();
+    child.replyOk('just text');
+    await expect(p).resolves.toEqual({ text: 'just text' });
+    host.shutdown();
+  });
+
+  it('correlates replies by id and reuses one child across calls', async () => {
+    const child = new FakeChild();
+    const { fork, calls } = forkFactory([child]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+
+    const p1 = host.transcribe({ ...REQ, samples: new Float32Array([1]) });
+    await tick();
+    const p2 = host.transcribe({ ...REQ, samples: new Float32Array([2]) });
+    await tick();
+    expect(child.sent.map((m) => m.id)).toEqual([1, 2]);
+    expect(calls()).toBe(1);
+    // Reply out of order — id correlation must still settle each promise.
+    child.replyOkTo(2, 'two');
+    child.replyOkTo(1, 'one');
+    await expect(p1).resolves.toEqual({ text: 'one' });
+    await expect(p2).resolves.toEqual({ text: 'two' });
+    host.shutdown();
+  });
+
+  it('rejects a transcription error reply', async () => {
+    const child = new FakeChild();
+    const { fork } = forkFactory([child]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+    const p = host.transcribe(REQ);
+    await tick();
+    child.replyErr('runtime', 'boom');
+    await expect(p).rejects.toThrow(/runtime error: boom/);
+    host.shutdown();
+  });
+
+  it('restarts the sidecar once on a crash and completes on the fresh child', async () => {
+    const first = new FakeChild();
+    const second = new FakeChild();
+    const { fork, calls } = forkFactory([first, second]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+
+    const p = host.transcribe(REQ);
+    await tick();
+    expect(calls()).toBe(1);
+    first.crash(139); // dies with the request in flight
+    await tick();
+    expect(calls()).toBe(2);
+    second.replyOk('recovered');
+    await expect(p).resolves.toEqual({ text: 'recovered' });
+    host.shutdown();
+  });
+
+  it('gives up after a second consecutive crash', async () => {
+    const first = new FakeChild();
+    const second = new FakeChild();
+    const { fork } = forkFactory([first, second]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+    const p = host.transcribe(REQ);
+    await tick();
+    first.crash();
+    await tick();
+    second.crash();
+    await expect(p).rejects.toThrow(/sidecar exited/);
+    host.shutdown();
+  });
+
+  it('treats a spawn error as a crash', async () => {
+    const child = new FakeChild();
+    const second = new FakeChild();
+    const { fork } = forkFactory([child, second]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+    const p = host.transcribe(REQ);
+    await tick();
+    child.errorOut('ENOENT node');
+    await tick();
+    second.replyOk('after respawn');
+    await expect(p).resolves.toEqual({ text: 'after respawn' });
+    host.shutdown();
+  });
+
+  it('times out a hung transcription and kills the child', async () => {
+    const child = new FakeChild();
+    const { fork } = forkFactory([child]);
+    const host = new HostClient({
+      hostPath: '/x/sidecar.js',
+      env: {},
+      forkImpl: fork,
+      requestTimeoutMs: 10,
+    });
+    const p = host.transcribe(REQ);
+    await expect(p).rejects.toThrow(/timed out/);
+    expect(child.killed).toBe(true);
+    host.shutdown();
+  });
+
+  it('shutdown kills the child and rejects in-flight requests', async () => {
+    const child = new FakeChild();
+    const { fork } = forkFactory([child]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+    const p = host.transcribe(REQ);
+    await tick();
+    host.shutdown();
+    expect(child.killed).toBe(true);
+    await expect(p).rejects.toThrow(/shut down/);
+    // Further calls fail fast.
+    await expect(host.transcribe(REQ)).rejects.toThrow(/shut down/);
+  });
+});