@hxnnxs/opencode-voice 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project are documented here.
 
+## 0.1.9 - 2026-06-21
+
+### Fixed
+
+- Rebuilt the managed Windows `whisper-cli.exe` engine asset as a static MinGW binary so clean Windows installs do not need the Visual C++ runtime DLLs.
+- Fixed managed engine path handling so explicit `downloadDir` and Windows platform overrides are honored consistently.
+- Added streaming timeout protection and clearer VC++ runtime diagnostics to managed engine downloads and probes.
+
+## 0.1.8 - 2026-06-21
+
+### Fixed
+
+- Added a managed Windows recorder install: the plugin can now download, unpack, cache, and probe `ffmpeg.exe` itself before recording, so Windows voice input no longer depends on `ffmpeg-static` lifecycle scripts, npm recovery installs, or a user-installed recorder on `PATH`.
+- Extended `opencode-voice doctor` diagnostics to prepare and report the managed Windows recorder path, manifest, install error, and probe result.
+- Made managed native binary replacement retry-safe on Windows for both recorder and `whisper-cli` engine installs.
+
 ## 0.1.7 - 2026-06-17
 
 ### Fixed

package/README.md

@@ -112,7 +112,7 @@ Planned sidecar models:
 | -------- | ------ |
 | Linux    | one-command engine/model install; recording uses `arecord`, `ffmpeg`, or `sox` |
 | macOS    | one-command engine/model install; recording uses `ffmpeg` AVFoundation until the native recorder sidecar ships |
-| Windows  | one-command engine/model install; recording uses `ffmpeg` with DirectShow (system or bundled `ffmpeg` fallback) |
+| Windows  | one-command engine/model/recorder install; recording uses DirectShow through a managed cached `ffmpeg.exe`, with system/bundled ffmpeg fallback |
 
 ### Architecture
 
@@ -128,7 +128,7 @@ Files:
 - `index.js` - TUI plugin entrypoint, commands, dialogs, keymap layer
 - `lib/models.js` - model registry, cache paths, default settings
 - `lib/download.js` - resumable model download and SHA256 verification
-- `lib/engine.js` - recorder selection and `whisper-cli` transcription
+- `lib/engine.js` - recorder selection, managed Windows recorder install, and `whisper-cli` transcription
 - `lib/engines.js` - managed native engine download, status, import, and removal
 - `bin/opencode-voice.js` - install wrapper and diagnostics CLI
 

package/bin/opencode-voice.js

@@ -67,21 +67,41 @@ async function runtime() {
 
 async function doctor() {
   const {
-    commandExists,
+    ensureManagedRecorder,
     resolveCommand,
     getAudioDir,
     getCacheDir,
     getEngineStatus,
     getModelsDir,
+    getRecorderStatus,
     listMicrophones,
     probeEngine,
   } = await runtime();
 
+  const json = hasFlag("--json");
+  let recorderInstall = null;
+  let recorderInstallError = "";
+  if (process.platform === "win32") {
+    try {
+      recorderInstall = await ensureManagedRecorder(
+        {},
+        {},
+        json ? {} : { onProgress: printRecorderProgress, onRetry: printRecorderRetry },
+      );
+    } catch (error) {
+      recorderInstallError = error instanceof Error ? error.message : String(error);
+    }
+  }
+
+  const recorderOptions = process.platform === "win32" && recorderInstall?.resolvedBinary
+    ? { ffmpeg: recorderInstall.resolvedBinary, skipFfmpegStaticInstall: true }
+    : {};
   const engine = getEngineStatus("whisper.cpp");
   const probe = engine.resolvedBinary ? await probeEngine("whisper.cpp", engine.resolvedBinary) : { ok: false, message: "missing binary" };
-  const ffmpeg = resolveCommand("ffmpeg");
-  const arecord = resolveCommand("arecord");
-  const sox = resolveCommand("sox");
+  const recorder = getRecorderStatus(recorderOptions);
+  const ffmpeg = recorderInstall?.resolvedBinary || resolveCommand("ffmpeg", recorderOptions);
+  const arecord = resolveCommand("arecord", recorderOptions);
+  const sox = resolveCommand("sox", recorderOptions);
   const payload = {
     platform: `${process.platform}-${process.arch}`,
     cacheDir: getCacheDir(),
@@ -89,21 +109,24 @@ async function doctor() {
     recordingsDir: getAudioDir(),
     engine,
     probe,
+    recorder,
     recorders: {
       ffmpeg,
       arecord,
       sox,
-      ffmpegPresent: commandExists("ffmpeg"),
-      arecordPresent: commandExists("arecord"),
-      soxPresent: commandExists("sox"),
+      ffmpegPresent: Boolean(ffmpeg),
+      arecordPresent: Boolean(arecord),
+      soxPresent: Boolean(sox),
       ffmpegProbe: probeCommand(ffmpeg),
       arecordProbe: probeCommand(arecord, ["--help"]),
       soxProbe: probeCommand(sox, ["--help"]),
+      managedInstall: recorderInstall,
+      managedInstallError: recorderInstallError,
     },
-    microphones: listMicrophones(),
+    microphones: listMicrophones(recorderOptions),
   };
 
-  if (hasFlag("--json")) {
+  if (json) {
     console.log(JSON.stringify(payload, null, 2));
   } else {
     console.log(
@@ -118,13 +141,19 @@ async function doctor() {
         `Managed engine dir: ${engine.managedDir}`,
         `whisper-cli: ${engine.resolvedBinary || "missing"}`,
         `Probe: ${probe.ok ? "ok" : probe.message}`,
+        `Recorder source: ${recorder.source}`,
+        `Managed recorder dir: ${recorder.managedDir}`,
+        `Managed recorder installed: ${recorder.managedInstalled ? "yes" : "no"}`,
+        `Managed recorder version: ${recorder.manifest?.version || "missing"}`,
+        `Managed recorder probe: ${payload.recorders.ffmpegProbe.ok ? "ok" : payload.recorders.ffmpegProbe.message}`,
+        ...(recorderInstallError ? [`Managed recorder error: ${recorderInstallError}`] : []),
         `Recorders: ffmpeg=${payload.recorders.ffmpegPresent ? "yes" : "no"}${payload.recorders.ffmpeg ? ` (${payload.recorders.ffmpeg})` : ""}, arecord=${payload.recorders.arecordPresent ? "yes" : "no"}${payload.recorders.arecord ? ` (${payload.recorders.arecord})` : ""}, sox=${payload.recorders.soxPresent ? "yes" : "no"}${payload.recorders.sox ? ` (${payload.recorders.sox})` : ""}`,
         `Microphones: ${payload.microphones.join(", ")}`,
       ].join("\n"),
     );
   }
 
-  if (!engine.resolvedBinary || !probe.ok) process.exitCode = 1;
+  if (!engine.resolvedBinary || !probe.ok || (process.platform === "win32" && !payload.recorders.ffmpegProbe.ok)) process.exitCode = 1;
 }
 
 async function engineCommand() {
@@ -198,6 +227,21 @@ function printEngineRetry({ error, nextAttempt, attempts }) {
   console.warn(`engine retry ${nextAttempt}/${attempts}: ${error instanceof Error ? error.message : String(error)}`);
 }
 
+function printRecorderProgress(progress) {
+  const label = {
+    downloading: "download",
+    decompressing: "unpack",
+    probing: "probe",
+    done: "done",
+  }[progress.state] || progress.state || "recorder";
+  const percent = Number.isFinite(progress.percent) ? `${Math.round(progress.percent)}%` : "";
+  if (progress.state === "downloading" || progress.state === "done") console.log(`recorder ${label} ${percent}`.trim());
+}
+
+function printRecorderRetry({ error, nextAttempt, attempts }) {
+  console.warn(`recorder retry ${nextAttempt}/${attempts}: ${error instanceof Error ? error.message : String(error)}`);
+}
+
 async function installCommand() {
   const pluginArgs = args.filter((arg) => arg !== "--no-engine");
   const spawnOptions = { stdio: "inherit" };
@@ -215,6 +259,13 @@ async function installCommand() {
     const engine = await installManagedEngine("whisper.cpp", {}, {}, { onProgress: printEngineProgress, onRetry: printEngineRetry });
     console.log(`Managed voice engine ready: ${engine.managedBinary}`);
   }
+
+  if (process.platform === "win32") {
+    const { ensureManagedRecorder } = await runtime();
+    console.log("Installing managed Windows recorder...");
+    const recorder = await ensureManagedRecorder({}, {}, { onProgress: printRecorderProgress, onRetry: printRecorderRetry });
+    console.log(`Managed Windows recorder ready: ${recorder.managedBinary || recorder.resolvedBinary}`);
+  }
 }
 
 if (command === "install") await installCommand();

package/docs/README.es.md

@@ -110,7 +110,7 @@ Modelos sidecar planeados:
 | ---------- | ------ |
 | Linux      | instalación engine/model en una orden; la grabación usa `arecord`, `ffmpeg` o `sox` |
 | macOS      | instalación engine/model en una orden; la grabación usa `ffmpeg` AVFoundation hasta el native recorder sidecar |
-| Windows    | instalación one-command de engine/model; grabación con `ffmpeg` + DirectShow (desde ffmpeg del sistema o fallback incluido) |
+| Windows    | instalación one-command de engine/model/recorder; grabación con DirectShow mediante `ffmpeg.exe` managed en caché, con fallback a ffmpeg del sistema/incluido |
 
 ### Arquitectura
 
@@ -126,7 +126,7 @@ Archivos:
 - `index.js` - entrada TUI, comandos, dialogs, keymap layer
 - `lib/models.js` - registry de modelos, cache paths, default settings
 - `lib/download.js` - descarga resumible y verificación SHA256
-- `lib/engine.js` - selección de recorder y transcripción con `whisper-cli`
+- `lib/engine.js` - selección de recorder, instalación managed del recorder Windows y transcripción con `whisper-cli`
 - `lib/engines.js` - descarga, estado, importación y eliminación de managed native engine
 - `bin/opencode-voice.js` - install wrapper y diagnostics CLI
 

package/docs/README.ru.md

@@ -110,7 +110,7 @@ Hold-to-talk отключен по умолчанию, потому что termi
 | --------- | ------ |
 | Linux     | one-command engine/model install; запись использует `arecord`, `ffmpeg` или `sox` |
 | macOS     | one-command engine/model install; запись использует `ffmpeg` AVFoundation до native recorder sidecar |
-| Windows   | one-command engine/model install; запись через `ffmpeg` + DirectShow (через системный ffmpeg или встроенный fallback) |
+| Windows   | one-command engine/model/recorder install; запись через DirectShow и managed cached `ffmpeg.exe`, с fallback на системный/встроенный ffmpeg |
 
 ### Архитектура
 
@@ -126,7 +126,7 @@ Hold-to-talk отключен по умолчанию, потому что termi
 - `index.js` - TUI entrypoint, команды, dialogs, keymap layer
 - `lib/models.js` - registry моделей, cache paths, default settings
 - `lib/download.js` - resumable download и SHA256 verification
-- `lib/engine.js` - выбор recorder и transcription через `whisper-cli`
+- `lib/engine.js` - выбор recorder, managed Windows recorder install и transcription через `whisper-cli`
 - `lib/engines.js` - managed native engine download, status, import и removal
 - `bin/opencode-voice.js` - install wrapper и diagnostics CLI
 

package/docs/README.zh.md

@@ -110,7 +110,7 @@ ctrl+r -> 停止、转写并插入文本
 | ------- | ---- |
 | Linux   | 一条命令安装 engine/model；录音使用 `arecord`、`ffmpeg` 或 `sox` |
 | macOS   | 一条命令安装 engine/model；native recorder sidecar 发布前使用 `ffmpeg` AVFoundation |
-| Windows | 下载 engine/model 一条命令完成；通过 `ffmpeg` + DirectShow 录音（使用系统 ffmpeg 或内置备用） |
+| Windows | 一条命令安装 engine/model/recorder；通过 managed cached `ffmpeg.exe` + DirectShow 录音，并保留系统/内置 ffmpeg 备用 |
 
 ### 架构
 
@@ -126,7 +126,7 @@ ctrl+r -> 停止、转写并插入文本
 - `index.js` - TUI 插件入口、命令、dialogs、keymap layer
 - `lib/models.js` - 模型 registry、cache paths、default settings
 - `lib/download.js` - 可续传下载和 SHA256 校验
-- `lib/engine.js` - recorder 选择和 `whisper-cli` 转写
+- `lib/engine.js` - recorder 选择、managed Windows recorder 安装和 `whisper-cli` 转写
 - `lib/engines.js` - managed native engine 下载、状态、导入和移除
 - `bin/opencode-voice.js` - install wrapper 和 diagnostics CLI
 

package/index.js

@@ -1,6 +1,6 @@
 import { MODELS, DEFAULT_SETTINGS, PLUGIN_ID, formatSize, getCacheDir, getModel, getModelPath, isModelDownloaded, isModelFilePresent } from "./lib/models.js";
 import { downloadModel } from "./lib/download.js";
-import { VoiceRuntime, commandExists, listMicrophones, resolveCommand } from "./lib/engine.js";
+import { VoiceRuntime, ensureManagedRecorder, getRecorderStatus, listMicrophones, probeRecorder, resolveCommand } from "./lib/engine.js";
 import { getEngineStatus, importManagedEngine, installManagedEngine, probeEngine, removeManagedEngine } from "./lib/engines.js";
 
 const KV = {
@@ -141,6 +141,33 @@ function renderEngineInstallStatus(ctx, progress = {}) {
   );
 }
 
+function renderRecorderInstallStatus(ctx, progress = {}) {
+  const percent = Math.max(0, Math.min(100, progress.percent || 0));
+  const state = {
+    downloading: "Downloading Windows recorder",
+    decompressing: "Unpacking ffmpeg",
+    probing: "Checking ffmpeg",
+    done: "Windows recorder ready",
+  }[progress.state] || "Preparing Windows recorder";
+  const attempt = progress.attempts > 1 ? `${progress.attempt} of ${progress.attempts}` : "single pass";
+
+  setDialog(ctx, "xlarge", () =>
+    ctx.api.ui.DialogAlert({
+      title: "Installing Windows recorder",
+      message: [
+        "ffmpeg DirectShow",
+        "",
+        state,
+        progressLine(percent),
+        "",
+        progress.total ? `${formatBytes(progress.downloaded || 0)} of ${formatBytes(progress.total)}` : "Fetching recorder binary",
+        `Attempt ${attempt}`,
+        "This is downloaded once into the managed opencode-voice cache.",
+      ].join("\n"),
+    }),
+  );
+}
+
 function modelStatus(model, options, settings) {
   if (!model.implemented) return "planned";
   if (isModelFilePresent(model, options, settings) && !isModelDownloaded(model, options, settings)) return "needs verification";
@@ -216,6 +243,30 @@ async function ensureEngineReady(ctx, settings) {
   return true;
 }
 
+async function ensureRecorderReady(ctx, settings) {
+  if (process.platform !== "win32") return true;
+
+  const commandOptions = { ...ctx.options, downloadDir: settings.downloadDir, skipFfmpegStaticInstall: true };
+  const current = getRecorderStatus(commandOptions, settings);
+  if (current.resolvedBinary) {
+    const probe = await probeRecorder(current.resolvedBinary);
+    if (probe.ok) return true;
+  }
+
+  renderRecorderInstallStatus(ctx, { state: "downloading", downloaded: 0, total: 0, percent: 0, attempt: 1, attempts: 5 });
+  toast(ctx.api, "Installing local Windows recorder...");
+  await ensureManagedRecorder(commandOptions, settings, {
+    retries: 5,
+    onProgress: (progress) => renderRecorderInstallStatus(ctx, progress),
+    onRetry: ({ error, nextAttempt, attempts }) => {
+      renderRecorderInstallStatus(ctx, { state: "downloading", downloaded: 0, total: 0, percent: 0, attempt: nextAttempt, attempts });
+      toast(ctx.api, `Recorder install retry ${nextAttempt}/${attempts}: ${error instanceof Error ? error.message : String(error)}`, "warning");
+    },
+  });
+  toast(ctx.api, "Windows recorder installed", "success");
+  return true;
+}
+
 function showModelPicker(ctx, firstRun = false) {
   const settings = readSettings(ctx.api.kv);
   setDialog(ctx, "large", () =>
@@ -325,8 +376,9 @@ function showLanguagePicker(ctx) {
 
 function showMicrophonePicker(ctx) {
   const settings = readSettings(ctx.api.kv);
+  const commandOptions = { ...ctx.options, downloadDir: settings.downloadDir, skipFfmpegStaticInstall: true };
   const placeholder = process.platform === "win32" ? "default, audio=default, \"Microphone (Name)\"" : "default, hw:0,0, pulse, :0, ...";
-  const devices = listMicrophones();
+  const devices = listMicrophones(commandOptions);
   setDialog(ctx, "large", () =>
     ctx.api.ui.DialogSelect({
       title: "Voice microphone",
@@ -360,15 +412,20 @@ function showMicrophonePicker(ctx) {
 function showDiagnostics(ctx) {
   const settings = readSettings(ctx.api.kv);
   const model = getModel(settings.model);
-  const commandOptions = { ...ctx.options, downloadDir: settings.downloadDir };
+  const commandOptions = { ...ctx.options, downloadDir: settings.downloadDir, skipFfmpegStaticInstall: true };
   const whisperCli = resolveCommand("whisper-cli", commandOptions);
   const ffmpeg = resolveCommand("ffmpeg", commandOptions);
   const arecord = resolveCommand("arecord", commandOptions);
   const sox = resolveCommand("sox", commandOptions);
   const engine = getEngineStatus("whisper.cpp", ctx.options, settings);
+  const recorder = getRecorderStatus(commandOptions, settings);
   const lines = [
     `Platform: ${process.platform}-${process.arch}`,
     `Recorder: ffmpeg=${ffmpeg ? "yes" : "no"}${ffmpeg ? ` (${ffmpeg})` : ""}, arecord=${arecord ? "yes" : "no"}, sox=${sox ? "yes" : "no"}`,
+    `Recorder source: ${recorder.source}`,
+    `Managed recorder dir: ${recorder.managedDir}`,
+    `Managed recorder installed: ${recorder.managedInstalled ? "yes" : "no"}`,
+    `Managed recorder version: ${recorder.manifest?.version || "missing"}`,
     `Engine: ${engine.id}`,
     `Engine source: ${engine.source}`,
     `whisper-cli: ${whisperCli || "missing"}`,
@@ -665,8 +722,9 @@ async function startVoice(ctx, submit = false, hold = false) {
 
   try {
     await ensureEngineReady(ctx, settings);
+    await ensureRecorderReady(ctx, settings);
   } catch (error) {
-    showError(ctx, "Engine install failed", error);
+    showError(ctx, "Voice runtime setup failed", error);
     return;
   }
 

package/lib/engine.js

@@ -4,17 +4,48 @@ import path from "node:path";
 import { createRequire } from "node:module";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { ensureDir } from "./download.js";
-import { getAudioDir, getEnginesDir, getModelPath } from "./models.js";
+import { createGunzip } from "node:zlib";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { ensureDir, replaceFile, sha256 } from "./download.js";
+import { getAudioDir, getCacheDir, getEnginesDir, getModelPath } from "./models.js";
 
 const require = createRequire(import.meta.url);
 const FFMPEG_STATIC_PACKAGE = "ffmpeg-static@^5.2.0";
+const FFMPEG_STATIC_RELEASE = "b6.1.1";
+const FFMPEG_STATIC_BASE_URL = "https://github.com/eugeneware/ffmpeg-static/releases/download";
+const DEFAULT_RECORDER_DOWNLOAD_RETRIES = 5;
 const PLUGIN_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 let ffmpegStaticPathCache;
 let ffmpegStaticInstallAttempted = false;
 
 const RECORDING_MIN_BYTES = 44;
 
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function normalizeArch(value) {
+  if (value === "amd64") return "x64";
+  if (value === "x86") return "ia32";
+  if (value === "aarch64") return "arm64";
+  return value;
+}
+
+function windowsFfmpegPlatform(options = {}) {
+  const platform = options.platform || process.platform;
+  const arch = normalizeArch(options.arch || process.arch);
+  return { platform, arch, key: `${platform}-${arch}` };
+}
+
+function isWindows(options = {}) {
+  return (options.platform || process.platform) === "win32";
+}
+
+function withDownloadDir(options = {}, settings = {}) {
+  return { ...options, downloadDir: settings.downloadDir || options.downloadDir };
+}
+
 function isExecutable(file) {
   try {
     fs.accessSync(file, fs.constants.X_OK);
@@ -24,8 +55,8 @@ function isExecutable(file) {
   }
 }
 
-function executableExtensions() {
-  if (process.platform !== "win32") return [""];
+function executableExtensions(options = {}) {
+  if (!isWindows(options)) return [""];
   return (process.env.PATHEXT || ".EXE;.CMD;.BAT")
     .split(";")
     .map((entry) => entry.trim().toLowerCase())
@@ -33,15 +64,15 @@ function executableExtensions() {
     .filter((entry) => entry.startsWith("."));
 }
 
-function resolveExecutable(file) {
+function resolveExecutable(file, options = {}) {
   const normalized = path.resolve(file);
   if (isExecutable(normalized)) return normalized;
 
-  if (path.extname(normalized) || process.platform !== "win32") {
+  if (path.extname(normalized) || !isWindows(options)) {
     return "";
   }
 
-  for (const ext of executableExtensions()) {
+  for (const ext of executableExtensions(options)) {
     const candidate = `${normalized}${ext}`;
     if (isExecutable(candidate)) return candidate;
   }
@@ -49,11 +80,329 @@ function resolveExecutable(file) {
   return "";
 }
 
-function executableNames(command) {
+function managedFfmpegDir(options = {}, settings = {}) {
+  const platform = windowsFfmpegPlatform(options);
+  return path.join(getCacheDir(options, settings), "recorders", "ffmpeg-static", platform.key);
+}
+
+export function getManagedRecorderBinary(options = {}, settings = {}) {
+  const platform = windowsFfmpegPlatform(options);
+  return path.join(managedFfmpegDir(options, settings), platform.platform === "win32" ? "ffmpeg.exe" : "ffmpeg");
+}
+
+export function getManagedRecorderManifestPath(options = {}, settings = {}) {
+  return path.join(managedFfmpegDir(options, settings), "manifest.json");
+}
+
+export function readManagedRecorderManifest(options = {}, settings = {}) {
+  const file = getManagedRecorderManifestPath(options, settings);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function temporaryBinaryPath(binaryPath) {
+  const extension = path.extname(binaryPath);
+  if (!extension) return `${binaryPath}.tmp-${process.pid}`;
+  return path.join(path.dirname(binaryPath), `${path.basename(binaryPath, extension)}.tmp-${process.pid}${extension}`);
+}
+
+function selectManagedRecorderAsset(options = {}) {
+  const platform = windowsFfmpegPlatform(options);
+  if (platform.platform !== "win32") throw new Error(`Managed ffmpeg recorder is only available for Windows, got ${platform.key}`);
+
+  const assetArch = platform.arch === "arm64" ? "x64" : platform.arch;
+  if (!new Set(["x64", "ia32"]).has(assetArch)) throw new Error(`No managed ffmpeg recorder asset for ${platform.key}`);
+
+  const assetKey = `${platform.platform}-${assetArch}`;
+  return {
+    platform,
+    assetKey,
+    emulated: assetArch !== platform.arch,
+    url: `${FFMPEG_STATIC_BASE_URL}/${FFMPEG_STATIC_RELEASE}/ffmpeg-${assetKey}.gz`,
+  };
+}
+
+function recorderSource(resolved, managedBinary) {
+  if (!resolved) return "missing";
+  if (path.resolve(resolved) === path.resolve(managedBinary)) return "managed";
+  return "system-or-bundled";
+}
+
+function recorderDownloadTimeoutMs(options = {}, hooks = {}) {
+  return Number(options.recorderDownloadTimeoutMs || options.downloadTimeoutMs || hooks.timeoutMs || 120000);
+}
+
+async function fetchRecorderWithTimeout(url, timeoutMs) {
+  const controller = new AbortController();
+  let timer;
+  const reset = () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => controller.abort(), timeoutMs);
+  };
+  const clear = () => clearTimeout(timer);
+  reset();
+
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    return { response, signal: controller.signal, reset, clear };
+  } catch (error) {
+    clear();
+    if (error?.name === "AbortError") throw new Error(`Recorder download timed out after ${Math.round(timeoutMs / 1000)}s`);
+    throw error;
+  }
+}
+
+function recorderDownloadError(error, url, timeoutMs) {
+  if (error?.name === "AbortError" || error?.code === "ABORT_ERR") {
+    return new Error(`Recorder download timed out or stalled from ${url} after ${Math.round(timeoutMs / 1000)}s`);
+  }
+  return error;
+}
+
+async function downloadRecorderAsset(sourceUrl, compressedFile, hooks = {}, attempt = 1, attempts = 1, options = {}) {
+  if (sourceUrl.startsWith("file://") || !/^https?:\/\//.test(sourceUrl)) {
+    const source = sourceUrl.startsWith("file://") ? new URL(sourceUrl) : path.resolve(sourceUrl);
+    const stat = await fs.promises.stat(source);
+    let downloaded = 0;
+    hooks.onProgress?.({ state: "downloading", downloaded, total: stat.size, percent: 0, attempt, attempts });
+    const progress = new Transform({
+      transform(chunk, _encoding, callback) {
+        downloaded += chunk.length ?? chunk.byteLength ?? 0;
+        hooks.onProgress?.({ state: "downloading", downloaded, total: stat.size, percent: stat.size ? (downloaded / stat.size) * 100 : 0, attempt, attempts });
+        callback(null, chunk);
+      },
+    });
+    await pipeline(fs.createReadStream(source), progress, fs.createWriteStream(compressedFile));
+    return;
+  }
+
+  const timeoutMs = recorderDownloadTimeoutMs(options, hooks);
+  const request = await fetchRecorderWithTimeout(sourceUrl, timeoutMs);
+  const response = request.response;
+
+  try {
+    if (!response.ok) throw new Error(`Recorder download failed from ${sourceUrl}: HTTP ${response.status}`);
+    const contentLength = Number(response.headers.get("content-length") || 0);
+    let downloaded = 0;
+    hooks.onProgress?.({ state: "downloading", downloaded, total: contentLength, percent: 0, attempt, attempts });
+
+    const body = response.body?.getReader ? Readable.fromWeb(response.body) : response.body;
+    if (!body) throw new Error("Recorder download failed: empty response body");
+
+    const progress = new Transform({
+      transform(chunk, _encoding, callback) {
+        request.reset();
+        downloaded += chunk.length ?? chunk.byteLength ?? 0;
+        hooks.onProgress?.({ state: "downloading", downloaded, total: contentLength, percent: contentLength ? (downloaded / contentLength) * 100 : 0, attempt, attempts });
+        callback(null, chunk);
+      },
+    });
+
+    try {
+      await pipeline(body, progress, fs.createWriteStream(compressedFile), { signal: request.signal });
+    } catch (error) {
+      throw recorderDownloadError(error, sourceUrl, timeoutMs);
+    }
+  } finally {
+    request.clear();
+  }
+}
+
+export async function probeRecorder(binaryPath, options = {}) {
+  if (!binaryPath) return { ok: false, message: "missing binary" };
+
+  return new Promise((resolve) => {
+    let output = "";
+    let settled = false;
+    let timer;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+
+    let proc;
+    try {
+      proc = spawn(binaryPath, ["-version"], {
+        stdio: ["ignore", "pipe", "pipe"],
+        env: {
+          ...process.env,
+          PATH: [path.dirname(binaryPath), process.env.PATH].filter(Boolean).join(path.delimiter),
+          ...options.env,
+        },
+      });
+    } catch (error) {
+      finish({ ok: false, message: error instanceof Error ? error.message : String(error) });
+      return;
+    }
+
+    timer = setTimeout(() => {
+      try {
+        proc.kill("SIGKILL");
+      } catch {}
+      finish({ ok: false, message: "probe timed out" });
+    }, options.timeoutMs || 10000);
+
+    proc.stdout.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    proc.stderr.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    proc.on("error", (error) => finish({ ok: false, message: error.message }));
+    proc.on("exit", (code) => {
+      const versionLine = output.split(/\r?\n/).filter(Boolean)[0] || "";
+      const ok = code === 0 && /ffmpeg version/i.test(output);
+      finish({ ok, message: ok ? "ok" : `unexpected ffmpeg probe output${typeof code === "number" ? ` (exit ${code})` : ""}`, versionLine });
+    });
+  });
+}
+
+async function writeManagedRecorderManifest(managedBinary, source, options = {}, settings = {}) {
+  const hash = await sha256(managedBinary);
+  const stat = await fs.promises.stat(managedBinary);
+  const manifest = {
+    schema: "opencode-voice.recorder-install.v1",
+    id: "ffmpeg",
+    kind: "cli",
+    command: "ffmpeg",
+    platform: windowsFfmpegPlatform(options).key,
+    version: FFMPEG_STATIC_RELEASE,
+    source,
+    files: [{ path: path.basename(managedBinary), sha256: hash, size: stat.size }],
+    installedAt: new Date().toISOString(),
+  };
+
+  await fs.promises.writeFile(getManagedRecorderManifestPath(options, settings), `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+export function getRecorderStatus(options = {}, settings = {}) {
+  const commandOptions = withDownloadDir(options, settings);
+  const managedDir = managedFfmpegDir(options, settings);
+  const managedBinary = getManagedRecorderBinary(options, settings);
+  const manifest = readManagedRecorderManifest(options, settings);
+  const resolvedBinary = resolveCommand("ffmpeg", commandOptions);
+
+  return {
+    id: "ffmpeg",
+    command: "ffmpeg",
+    platform: windowsFfmpegPlatform(options).key,
+    supported: isWindows(options),
+    managedDir,
+    managedBinary,
+    managedInstalled: isExecutable(managedBinary),
+    manifest,
+    resolvedBinary,
+    source: recorderSource(resolvedBinary, managedBinary),
+  };
+}
+
+export async function installManagedRecorder(options = {}, settings = {}, hooks = {}) {
+  const commandOptions = withDownloadDir(options, settings);
+  const asset = selectManagedRecorderAsset(commandOptions);
+  const managedDir = managedFfmpegDir(commandOptions, settings);
+  const managedBinary = getManagedRecorderBinary(commandOptions, settings);
+  if (!hooks.force && fs.existsSync(managedBinary)) {
+    const probe = await probeRecorder(managedBinary);
+    if (probe.ok) return { manifest: readManagedRecorderManifest(commandOptions, settings), managedBinary, probe, skipped: true };
+  }
+
+  await ensureDir(managedDir);
+  const compressedFile = path.join(managedDir, `${path.basename(asset.url)}.download`);
+  const tmpBinary = temporaryBinaryPath(managedBinary);
+  const attempts = Number(options.recorderDownloadRetries || hooks.retries || DEFAULT_RECORDER_DOWNLOAD_RETRIES);
+  let lastError;
+
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      await fs.promises.unlink(compressedFile).catch(() => {});
+      await fs.promises.unlink(tmpBinary).catch(() => {});
+      await downloadRecorderAsset(asset.url, compressedFile, hooks, attempt, attempts, commandOptions);
+
+      const compressedSize = fs.existsSync(compressedFile) ? fs.statSync(compressedFile).size : 0;
+      hooks.onProgress?.({ state: "decompressing", downloaded: compressedSize, total: compressedSize, percent: 100, attempt, attempts });
+      await pipeline(fs.createReadStream(compressedFile), createGunzip(), fs.createWriteStream(tmpBinary));
+      await fs.promises.chmod(tmpBinary, 0o755);
+
+      hooks.onProgress?.({ state: "probing", downloaded: fs.statSync(tmpBinary).size, total: fs.statSync(tmpBinary).size, percent: 100, attempt, attempts });
+      const probe = await probeRecorder(tmpBinary);
+      if (!probe.ok) throw new Error(`Recorder probe failed: ${probe.message}`);
+
+      await replaceFile(tmpBinary, managedBinary);
+      await fs.promises.unlink(compressedFile).catch(() => {});
+      const manifest = await writeManagedRecorderManifest(
+        managedBinary,
+        {
+          type: "ffmpeg-static-release",
+          release: FFMPEG_STATIC_RELEASE,
+          url: asset.url,
+          assetPlatform: asset.assetKey,
+          emulated: asset.emulated,
+        },
+        commandOptions,
+        settings,
+      );
+      const installedSize = fs.statSync(managedBinary).size;
+      hooks.onProgress?.({ state: "done", downloaded: installedSize, total: installedSize, percent: 100, attempt, attempts });
+      return { manifest, managedBinary, probe, skipped: false };
+    } catch (error) {
+      lastError = error;
+      await fs.promises.unlink(tmpBinary).catch(() => {});
+      if (attempt >= attempts) break;
+      hooks.onRetry?.({ error, attempt, attempts, nextAttempt: attempt + 1 });
+      await sleep(Math.min(1000 * attempt, 3000));
+    }
+  }
+
+  throw lastError;
+}
+
+export async function ensureManagedRecorder(options = {}, settings = {}, hooks = {}) {
+  const commandOptions = withDownloadDir(options, settings);
+  if (!isWindows(commandOptions)) return { ...getRecorderStatus(commandOptions, settings), ok: true, skipped: true, unsupported: true };
+
+  const existingOptions = { ...commandOptions, skipFfmpegStaticInstall: true };
+  const current = getRecorderStatus(existingOptions, settings);
+  if (current.resolvedBinary) {
+    const probe = await probeRecorder(current.resolvedBinary);
+    if (probe.ok) return { ...current, ok: true, probe, skipped: true };
+  }
+
+  try {
+    const installed = await installManagedRecorder(commandOptions, settings, hooks);
+    return { ...getRecorderStatus(commandOptions, settings), ...installed, ok: true };
+  } catch (error) {
+    const resolvedBinary = resolveRecorderFallback(existingOptions, settings);
+    if (resolvedBinary) {
+      const probe = await probeRecorder(resolvedBinary);
+      if (probe.ok) {
+        return {
+          ...getRecorderStatus(commandOptions, settings),
+          resolvedBinary,
+          source: recorderSource(resolvedBinary, getManagedRecorderBinary(commandOptions, settings)),
+          ok: true,
+          fallback: true,
+          managedError: error instanceof Error ? error.message : String(error),
+          probe,
+        };
+      }
+    }
+
+    throw new Error(`Windows ffmpeg recorder install failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function executableNames(command, options = {}) {
   const names = [command];
   if (path.extname(command)) return names;
 
-  if (process.platform === "win32") {
+  if (isWindows(options)) {
     const extensions = (process.env.PATHEXT || ".EXE;.CMD;.BAT")
       .split(";")
       .map((item) => item.trim().toLowerCase())
@@ -64,7 +413,7 @@ function executableNames(command) {
   return [...new Set(names)];
 }
 
-function bundledFfmpegPath() {
+function bundledFfmpegPath(options = {}) {
   if (process.platform !== "win32") return "";
   if (ffmpegStaticPathCache !== undefined) return ffmpegStaticPathCache;
 
@@ -98,7 +447,7 @@ function bundledFfmpegPath() {
 
   let candidate = resolveFromDependency();
   if (!candidate) candidate = resolveFromLocalModule();
-  if (!candidate && !ffmpegStaticInstallAttempted) {
+  if (!candidate && !ffmpegStaticInstallAttempted && !options.skipFfmpegStaticInstall) {
     ffmpegStaticInstallAttempted = true;
     if (installDependency()) {
       candidate = resolveFromDependency();
@@ -106,6 +455,7 @@ function bundledFfmpegPath() {
   }
 
   if (!candidate) candidate = resolveFromLocalModule();
+  if (!candidate && options.skipFfmpegStaticInstall) return "";
 
   ffmpegStaticPathCache = candidate || "";
   return ffmpegStaticPathCache;
@@ -133,16 +483,19 @@ function candidateCommands(command, options = {}) {
   }
 
   if (command === "ffmpeg") {
-    const bundled = bundledFfmpegPath();
+    if (options.ffmpeg) candidates.push(options.ffmpeg);
+    if (process.env.OPENCODE_VOICE_FFMPEG) candidates.push(process.env.OPENCODE_VOICE_FFMPEG);
+    if (isWindows(options)) candidates.push(getManagedRecorderBinary(options, options));
+    const bundled = bundledFfmpegPath(options);
     if (bundled) candidates.push(bundled);
   }
 
   const bundledDir = getBundledEngineDir(command, options);
   if (bundledDir) {
-    for (const name of executableNames(command)) candidates.push(path.join(bundledDir, name));
+    for (const name of executableNames(command, options)) candidates.push(path.join(bundledDir, name));
   }
 
-  candidates.push(...executableNames(command));
+  candidates.push(...executableNames(command, options));
 
   const fallbackDirs = [
     path.join(os.homedir(), ".local", "bin"),
@@ -153,13 +506,13 @@ function candidateCommands(command, options = {}) {
     "/bin",
   ];
 
-  if (process.platform === "win32") {
+  if (isWindows(options)) {
     const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
     fallbackDirs.unshift(path.join(localAppData, "opencode-voice", "bin"));
   }
 
   for (const dir of fallbackDirs) {
-    for (const name of executableNames(command)) candidates.push(path.join(dir, name));
+    for (const name of executableNames(command, options)) candidates.push(path.join(dir, name));
   }
 
   return [...new Set(candidates.filter(Boolean))];
@@ -168,14 +521,34 @@ function candidateCommands(command, options = {}) {
 export function resolveCommand(command, options = {}) {
   for (const candidate of candidateCommands(command, options)) {
     if (looksLikePath(candidate)) {
-      const resolved = resolveExecutable(candidate);
+      const resolved = resolveExecutable(candidate, options);
       if (resolved) return resolved;
       continue;
     }
 
     for (const dir of (process.env.PATH || "").split(path.delimiter).filter(Boolean)) {
       const file = path.join(dir, candidate);
-      if (isExecutable(file)) return file;
+      const resolved = resolveExecutable(file, options);
+      if (resolved) return resolved;
+    }
+  }
+
+  return null;
+}
+
+function resolveRecorderFallback(options = {}, settings = {}) {
+  const managedBinary = path.resolve(getManagedRecorderBinary(options, settings));
+  for (const candidate of candidateCommands("ffmpeg", options)) {
+    if (looksLikePath(candidate)) {
+      const resolved = resolveExecutable(candidate, options);
+      if (resolved && path.resolve(resolved) !== managedBinary) return resolved;
+      continue;
+    }
+
+    for (const dir of (process.env.PATH || "").split(path.delimiter).filter(Boolean)) {
+      const file = path.join(dir, candidate);
+      const resolved = resolveExecutable(file, options);
+      if (resolved && path.resolve(resolved) !== managedBinary) return resolved;
     }
   }
 
@@ -216,9 +589,9 @@ function parseWindowsMicrophones(stderr) {
   return [...devices].filter(Boolean);
 }
 
-export function listMicrophones() {
-  const arecordCommand = resolveCommand("arecord");
-  const ffmpegCommand = resolveCommand("ffmpeg");
+export function listMicrophones(options = {}) {
+  const arecordCommand = resolveCommand("arecord", options);
+  const ffmpegCommand = resolveCommand("ffmpeg", options);
 
   if (process.platform === "linux" && arecordCommand) {
     const result = spawnSync(arecordCommand, ["-L"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
@@ -416,9 +789,15 @@ export class VoiceRuntime {
 
     const dir = getAudioDir(this.options, settings);
     await ensureDir(dir);
+    const recorderSettings = { ...this.options, ...settings, downloadDir: settings.downloadDir || this.options.downloadDir };
+    const recorderReady = await ensureManagedRecorder(recorderSettings, settings).catch((error) => {
+      if (isWindows(recorderSettings)) throw error;
+      return null;
+    });
+    if (recorderReady?.resolvedBinary) recorderSettings.ffmpeg = recorderReady.resolvedBinary;
 
     const file = path.join(dir, `voice-${Date.now()}.wav`);
-    const recorders = buildRecorders(file, settings);
+    const recorders = buildRecorders(file, recorderSettings);
     const errors = [];
     this.recordingError = "";
 

package/lib/engines.js

@@ -9,7 +9,7 @@ import { sha256, ensureDir, replaceFile } from "./download.js";
 import { getCacheDir } from "./models.js";
 import { getBundledEngineDir, resolveCommand } from "./engine.js";
 
-export const DEFAULT_ENGINE_REGISTRY_URL = "https://github.com/ihxnnxs/opencode-voice/releases/download/v0.1.0/registry.json";
+export const DEFAULT_ENGINE_REGISTRY_URL = "https://github.com/ihxnnxs/opencode-voice/releases/download/v0.1.9/registry.json";
 
 const ENGINE = {
   id: "whisper.cpp",
@@ -19,13 +19,14 @@ const ENGINE = {
 };
 
 const DEFAULT_ENGINE_DOWNLOAD_RETRIES = 5;
+const DEFAULT_ENGINE_DOWNLOAD_TIMEOUT_MS = 120000;
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-function executableName() {
-  return process.platform === "win32" ? "whisper-cli.exe" : "whisper-cli";
+function executableName(options = {}) {
+  return (options.platform || process.platform) === "win32" ? "whisper-cli.exe" : "whisper-cli";
 }
 
 function temporaryBinaryPath(binaryPath) {
@@ -45,13 +46,17 @@ export function getEnginePlatformKey(options = {}) {
   return `${options.platform || process.platform}-${normalizePlatform(options.arch || process.arch)}`;
 }
 
+function withDownloadDir(options = {}, settings = {}) {
+  return { ...options, downloadDir: settings.downloadDir || options.downloadDir };
+}
+
 export function getManagedEngineDir(engineId = ENGINE.id, options = {}, settings = {}) {
   if (engineId !== ENGINE.id) throw new Error(`Unsupported engine: ${engineId}`);
-  return getBundledEngineDir(ENGINE.command, { ...options, downloadDir: settings.downloadDir });
+  return getBundledEngineDir(ENGINE.command, withDownloadDir(options, settings));
 }
 
 export function getManagedEngineBinary(engineId = ENGINE.id, options = {}, settings = {}) {
-  return path.join(getManagedEngineDir(engineId, options, settings), executableName());
+  return path.join(getManagedEngineDir(engineId, options, settings), executableName(options));
 }
 
 export function getEngineManifestPath(engineId = ENGINE.id, options = {}, settings = {}) {
@@ -77,32 +82,52 @@ function engineSource(resolved, managedBinary, options = {}) {
 }
 
 export function getEngineStatus(engineId = ENGINE.id, options = {}, settings = {}) {
-  const commandOptions = { ...options, downloadDir: settings.downloadDir };
-  const managedDir = getManagedEngineDir(engineId, options, settings);
-  const managedBinary = getManagedEngineBinary(engineId, options, settings);
-  const manifest = readEngineManifest(engineId, options, settings);
+  const commandOptions = withDownloadDir(options, settings);
+  const managedDir = getManagedEngineDir(engineId, commandOptions);
+  const managedBinary = getManagedEngineBinary(engineId, commandOptions);
+  const manifest = readEngineManifest(engineId, commandOptions);
   const resolvedBinary = resolveCommand(ENGINE.command, commandOptions);
 
   return {
     id: engineId,
     command: ENGINE.command,
-    platform: getEnginePlatformKey(options),
-    cacheDir: getCacheDir(options, settings),
+    platform: getEnginePlatformKey(commandOptions),
+    cacheDir: getCacheDir(commandOptions),
     managedDir,
     managedBinary,
     managedInstalled: fs.existsSync(managedBinary),
     manifest,
     resolvedBinary,
-    source: engineSource(resolvedBinary, managedBinary, options),
+    source: engineSource(resolvedBinary, managedBinary, commandOptions),
   };
 }
 
+function summarizeProbeOutput(output) {
+  return String(output || "").replace(/\s+/g, " ").trim().slice(0, 240);
+}
+
+function engineProbeMessage(message) {
+  const text = summarizeProbeOutput(message);
+  if (/\b(MSVCP140|VCOMP140|VCRUNTIME140|VCRUNTIME140_1|api-ms-win-crt)\b/i.test(text)) {
+    return `${text}; Windows VC++ runtime dependency is missing`;
+  }
+  return text || "unknown probe failure";
+}
+
 export async function probeEngine(engineId = ENGINE.id, binaryPath, options = {}) {
   if (engineId !== ENGINE.id) throw new Error(`Unsupported engine: ${engineId}`);
   if (!binaryPath) return { ok: false, message: "missing binary" };
 
   return new Promise((resolve) => {
     let output = "";
+    let settled = false;
+    let timer;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
     const localLib = path.join(os.homedir(), ".local", "lib");
     const env = {
       ...process.env,
@@ -112,11 +137,11 @@ export async function probeEngine(engineId = ENGINE.id, binaryPath, options = {}
       ...options.env,
     };
     const proc = spawn(binaryPath, ENGINE.probeArgs, { stdio: ["ignore", "pipe", "pipe"], env });
-    const timer = setTimeout(() => {
+    timer = setTimeout(() => {
       try {
         proc.kill("SIGKILL");
       } catch {}
-      resolve({ ok: false, message: "probe timed out" });
+      finish({ ok: false, message: "probe timed out" });
     }, options.timeoutMs || 10000);
 
     proc.stdout.on("data", (chunk) => {
@@ -126,13 +151,12 @@ export async function probeEngine(engineId = ENGINE.id, binaryPath, options = {}
       output += chunk.toString();
     });
     proc.on("error", (error) => {
-      clearTimeout(timer);
-      resolve({ ok: false, message: error.message });
+      finish({ ok: false, message: engineProbeMessage(error.message) });
     });
-    proc.on("exit", () => {
-      clearTimeout(timer);
+    proc.on("exit", (code, signal) => {
       const ok = ENGINE.probeContains.every((item) => output.includes(item));
-      resolve({ ok, message: ok ? "ok" : "unexpected whisper-cli help output" });
+      const detail = summarizeProbeOutput(output) || `exit ${code ?? signal ?? "unknown"}`;
+      finish({ ok, message: ok ? "ok" : engineProbeMessage(`unexpected whisper-cli help output: ${detail}`) });
     });
   });
 }
@@ -150,6 +174,14 @@ async function fetchWithTimeout(url, init = {}, timeoutMs = 60000) {
   }
 }
 
+function engineDownloadTimeoutMs(options = {}, hooks = {}) {
+  return Number(options.engineDownloadTimeoutMs || options.downloadTimeoutMs || hooks.timeoutMs || DEFAULT_ENGINE_DOWNLOAD_TIMEOUT_MS);
+}
+
+function engineDownloadTimeoutError(url, timeoutMs) {
+  return new Error(`Engine download stalled after ${Math.round(timeoutMs / 1000)}s: ${url}`);
+}
+
 async function readJsonUrl(url, options = {}) {
   if (url.startsWith("file://")) return JSON.parse(await fs.promises.readFile(new URL(url), "utf8"));
   if (!/^https?:\/\//.test(url)) return JSON.parse(await fs.promises.readFile(path.resolve(url), "utf8"));
@@ -201,7 +233,8 @@ async function downloadAsset(asset, compressedFile, hooks = {}, attempt = 1, att
     return;
   }
 
-  const response = await fetchWithTimeout(asset.url, {}, Number(options.downloadTimeoutMs || hooks.timeoutMs || 120000));
+  const timeoutMs = engineDownloadTimeoutMs(options, hooks);
+  const response = await fetchWithTimeout(asset.url, {}, timeoutMs);
   if (!response.ok) throw new Error(`Engine download failed: HTTP ${response.status}`);
 
   const contentLength = Number(response.headers.get("content-length") || asset.size || 0);
@@ -211,15 +244,31 @@ async function downloadAsset(asset, compressedFile, hooks = {}, attempt = 1, att
   const body = response.body?.getReader ? Readable.fromWeb(response.body) : response.body;
   if (!body) throw new Error("Engine download failed: empty response body");
 
+  const controller = new AbortController();
+  let stallTimer;
+  const resetStallTimer = () => {
+    clearTimeout(stallTimer);
+    stallTimer = setTimeout(() => controller.abort(), timeoutMs);
+  };
+
   const progress = new Transform({
     transform(chunk, _encoding, callback) {
+      resetStallTimer();
       downloaded += chunk.length ?? chunk.byteLength ?? 0;
       hooks.onProgress?.({ state: "downloading", downloaded, total: contentLength, percent: contentLength ? (downloaded / contentLength) * 100 : 0, attempt, attempts });
       callback(null, chunk);
     },
   });
 
-  await pipeline(body, progress, fs.createWriteStream(compressedFile));
+  resetStallTimer();
+  try {
+    await pipeline(body, progress, fs.createWriteStream(compressedFile), { signal: controller.signal });
+  } catch (error) {
+    if (error?.name === "AbortError") throw engineDownloadTimeoutError(asset.url, timeoutMs);
+    throw error;
+  } finally {
+    clearTimeout(stallTimer);
+  }
 }
 
 async function writeManifest(engineId, managedBinary, source, options = {}) {
@@ -244,29 +293,30 @@ async function writeManifest(engineId, managedBinary, source, options = {}) {
 export async function installManagedEngine(engineId = ENGINE.id, options = {}, settings = {}, hooks = {}) {
   if (engineId !== ENGINE.id) throw new Error(`Unsupported engine: ${engineId}`);
 
-  const managedDir = getManagedEngineDir(engineId, options, settings);
-  const managedBinary = getManagedEngineBinary(engineId, options, settings);
+  const commandOptions = withDownloadDir(options, settings);
+  const managedDir = getManagedEngineDir(engineId, commandOptions);
+  const managedBinary = getManagedEngineBinary(engineId, commandOptions);
   if (!hooks.force && fs.existsSync(managedBinary)) {
     const probe = await probeEngine(engineId, managedBinary);
-    if (probe.ok) return { manifest: readEngineManifest(engineId, options, settings), managedBinary, skipped: true };
+    if (probe.ok) return { manifest: readEngineManifest(engineId, commandOptions), managedBinary, skipped: true };
   }
 
   hooks.onProgress?.({ state: "registry", downloaded: 0, total: 0, percent: 0, attempt: 1, attempts: 1 });
-  const { url: registryUrl, registry } = await loadEngineRegistry(options);
-  const platform = getEnginePlatformKey(options);
+  const { url: registryUrl, registry } = await loadEngineRegistry(commandOptions);
+  const platform = getEnginePlatformKey(commandOptions);
   const { engine, asset } = selectEngineAsset(registry, engineId, platform);
 
   await ensureDir(managedDir);
   const compressedFile = path.join(managedDir, `${path.basename(asset.url || `${platform}.gz`)}.download`);
   const tmpBinary = temporaryBinaryPath(managedBinary);
-  const attempts = Number(options.engineDownloadRetries || hooks.retries || DEFAULT_ENGINE_DOWNLOAD_RETRIES);
+  const attempts = Number(commandOptions.engineDownloadRetries || hooks.retries || DEFAULT_ENGINE_DOWNLOAD_RETRIES);
   let lastError;
 
   for (let attempt = 1; attempt <= attempts; attempt++) {
     try {
       await fs.promises.unlink(compressedFile).catch(() => {});
       await fs.promises.unlink(tmpBinary).catch(() => {});
-      await downloadAsset(asset, compressedFile, hooks, attempt, attempts, options);
+      await downloadAsset(asset, compressedFile, hooks, attempt, attempts, commandOptions);
 
       hooks.onProgress?.({ state: "verifying", downloaded: asset.size || 0, total: asset.size || 0, percent: 100, attempt, attempts });
       if (asset.sha256 && (await sha256(compressedFile)) !== asset.sha256) throw new Error("Engine archive SHA256 mismatch");
@@ -282,8 +332,7 @@ export async function installManagedEngine(engineId = ENGINE.id, options = {}, s
       const probe = await probeEngine(engineId, tmpBinary);
       if (!probe.ok) throw new Error(`Engine probe failed: ${probe.message}`);
 
-      await fs.promises.unlink(managedBinary).catch(() => {});
-      await fs.promises.rename(tmpBinary, managedBinary);
+      await replaceFile(tmpBinary, managedBinary);
       await fs.promises.unlink(compressedFile).catch(() => {});
       const manifest = await writeManifest(
         engineId,
@@ -295,7 +344,7 @@ export async function installManagedEngine(engineId = ENGINE.id, options = {}, s
           version: engine.version || registry.version || "registry",
           upstream: engine.upstream,
         },
-        options,
+        commandOptions,
       );
       hooks.onProgress?.({ state: "done", downloaded: asset.binary?.size || asset.size || 0, total: asset.binary?.size || asset.size || 0, percent: 100, attempt, attempts });
       return { manifest, managedBinary, skipped: false };
@@ -319,8 +368,9 @@ export async function importManagedEngine(engineId = ENGINE.id, sourcePath, opti
   const stat = await fs.promises.stat(source).catch(() => null);
   if (!stat?.isFile()) throw new Error(`Engine binary not found: ${source}`);
 
-  const managedDir = getManagedEngineDir(engineId, options, settings);
-  const managedBinary = getManagedEngineBinary(engineId, options, settings);
+  const commandOptions = withDownloadDir(options, settings);
+  const managedDir = getManagedEngineDir(engineId, commandOptions);
+  const managedBinary = getManagedEngineBinary(engineId, commandOptions);
   const tmp = temporaryBinaryPath(managedBinary);
   await ensureDir(managedDir);
   await fs.promises.copyFile(source, tmp);
@@ -332,9 +382,8 @@ export async function importManagedEngine(engineId = ENGINE.id, sourcePath, opti
     throw new Error(`Imported binary failed probe: ${probe.message}`);
   }
 
-  await fs.promises.unlink(managedBinary).catch(() => {});
-  await fs.promises.rename(tmp, managedBinary);
-  const manifest = await writeManifest(engineId, managedBinary, { type: "local-file", path: source }, options);
+  await replaceFile(tmp, managedBinary);
+  const manifest = await writeManifest(engineId, managedBinary, { type: "local-file", path: source }, commandOptions);
   return { manifest, managedBinary };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hxnnxs/opencode-voice",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Local voice input plugin for OpenCode",
   "type": "module",
   "license": "MIT",