@hienlh/ppm 0.23.6 → 0.23.7

package/src/services/lsp/server-registry.ts

@@ -32,6 +32,14 @@ export interface LanguageServerDefinition {
   rootMarkers: string[];
   /** Shown verbatim when the command cannot be found. */
   installHint: string;
+  /**
+   * How the Install button installs this server, when PPM can install it at all.
+   *
+   * Unset for a server that needs a system package manager — `clangd`, `lua-language-server`
+   * and `solargraph` mean pacman, apt, brew or a gem, i.e. a password and a choice PPM has no
+   * business making. Those keep a command to copy and no button.
+   */
+  install?: LanguageServerInstall;
   /**
    * The npm package PPM depends on for this server, when it ships one.
    *
@@ -42,6 +50,25 @@ export interface LanguageServerDefinition {
   initializationOptions?: Record<string, unknown>;
 }
 
+/**
+ * What the Install button runs.
+ *
+ * `bun` and `go` both put the server inside PPM's own directory, so nothing the user installed
+ * is touched and `rm -rf` is the uninstall. `rustup` is the exception and has to be: a
+ * rust-analyzer belongs to a toolchain, and a private copy would be the wrong one as soon as a
+ * project pins a different toolchain.
+ *
+ * PPM never installs the *toolchain*. `go` and `rustup` are offered only where the host
+ * already has them — see `canInstall` in `lsp-install.ts`.
+ */
+export type LanguageServerInstall =
+  /** `bun add <packages>`; the first package provides `command`, the rest are what it needs. */
+  | { with: "bun"; packages: string[] }
+  /** `go install <module>` with `GOBIN` pointed at PPM's own bin directory. */
+  | { with: "go"; module: string }
+  /** `rustup component add <component>`, in whichever toolchain the project selects. */
+  | { with: "rustup"; component: string };
+
 /**
  * File extension to LSP language id.
  *
@@ -110,6 +137,7 @@ export const LANGUAGE_SERVERS: LanguageServerDefinition[] = [
     // start against it with "provides no tsserver" — which reads like a broken
     // install rather than the wrong major version.
     installHint: "bun add -g typescript-language-server typescript@5",
+    install: { with: "bun", packages: ["typescript-language-server", "typescript@5"] },
     // Shipped with PPM, so this one works on a fresh install with nothing else done. The
     // project's own copy still wins where there is one — a repository pinned to TypeScript 4
     // has to be analysed by its own server, not by whatever PPM happens to carry.
@@ -153,6 +181,7 @@ export const LANGUAGE_SERVERS: LanguageServerDefinition[] = [
     args: ["--stdio"],
     rootMarkers: ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile"],
     installHint: "bun add -g pyright",
+    install: { with: "bun", packages: ["pyright"] },
   },
   {
     id: "gopls",
@@ -162,6 +191,9 @@ export const LANGUAGE_SERVERS: LanguageServerDefinition[] = [
     args: [],
     rootMarkers: ["go.work", "go.mod"],
     installHint: "go install golang.org/x/tools/gopls@latest",
+    // Built by the host's own Go, into PPM's directory: `GOBIN` is what decides where the
+    // binary lands, so `~/go/bin` is left exactly as the user arranged it. 10.6 s here.
+    install: { with: "go", module: "golang.org/x/tools/gopls@latest" },
   },
   {
     id: "rust-analyzer",
@@ -171,6 +203,11 @@ export const LANGUAGE_SERVERS: LanguageServerDefinition[] = [
     args: [],
     rootMarkers: ["Cargo.toml"],
     installHint: "rustup component add rust-analyzer",
+    // The one server PPM does not keep in its own directory: rust-analyzer belongs to a
+    // *toolchain*, and a copy of its own would be the wrong one the moment a project pins a
+    // different one. `rustup which` is then both the lookup and the installed-check — it exits
+    // non-zero with "unknown binary" when the component is absent, in 3 ms.
+    install: { with: "rustup", component: "rust-analyzer" },
   },
   {
     id: "clangd",
@@ -189,6 +226,7 @@ export const LANGUAGE_SERVERS: LanguageServerDefinition[] = [
     args: ["--stdio"],
     rootMarkers: ["package.json"],
     installHint: "bun add -g vscode-langservers-extracted",
+    install: { with: "bun", packages: ["vscode-langservers-extracted"] },
   },
   {
     id: "html",
@@ -198,6 +236,7 @@ export const LANGUAGE_SERVERS: LanguageServerDefinition[] = [
     args: ["--stdio"],
     rootMarkers: ["package.json"],
     installHint: "bun add -g vscode-langservers-extracted",
+    install: { with: "bun", packages: ["vscode-langservers-extracted"] },
   },
   {
     id: "css",
@@ -207,6 +246,7 @@ export const LANGUAGE_SERVERS: LanguageServerDefinition[] = [
     args: ["--stdio"],
     rootMarkers: ["package.json"],
     installHint: "bun add -g vscode-langservers-extracted",
+    install: { with: "bun", packages: ["vscode-langservers-extracted"] },
   },
   {
     id: "yaml",
@@ -216,6 +256,7 @@ export const LANGUAGE_SERVERS: LanguageServerDefinition[] = [
     args: ["--stdio"],
     rootMarkers: [],
     installHint: "bun add -g yaml-language-server",
+    install: { with: "bun", packages: ["yaml-language-server"] },
   },
   {
     id: "bash",
@@ -225,6 +266,7 @@ export const LANGUAGE_SERVERS: LanguageServerDefinition[] = [
     args: ["start"],
     rootMarkers: [],
     installHint: "bun add -g bash-language-server",
+    install: { with: "bun", packages: ["bash-language-server"] },
   },
   {
     id: "intelephense",
@@ -234,6 +276,7 @@ export const LANGUAGE_SERVERS: LanguageServerDefinition[] = [
     args: ["--stdio"],
     rootMarkers: ["composer.json"],
     installHint: "bun add -g intelephense",
+    install: { with: "bun", packages: ["intelephense"] },
   },
   {
     id: "solargraph",
@@ -261,6 +304,7 @@ export const LANGUAGE_SERVERS: LanguageServerDefinition[] = [
     args: ["--stdio"],
     rootMarkers: ["package.json"],
     installHint: "bun add -g @vue/language-server",
+    install: { with: "bun", packages: ["@vue/language-server"] },
   },
   {
     id: "svelte",
@@ -270,6 +314,7 @@ export const LANGUAGE_SERVERS: LanguageServerDefinition[] = [
     args: ["--stdio"],
     rootMarkers: ["package.json"],
     installHint: "bun add -g svelte-language-server",
+    install: { with: "bun", packages: ["svelte-language-server"] },
   },
 ];
 
@@ -282,6 +327,26 @@ export function serverById(id: string): LanguageServerDefinition | undefined {
   return LANGUAGE_SERVERS.find((s) => s.id === id);
 }
 
+/**
+ * The other servers that an uninstall of this one would also take away.
+ *
+ * One npm package can provide several servers — `vscode-langservers-extracted` is JSON, HTML
+ * and CSS at once — so `bun remove` of it removes all three whichever row the button was on.
+ * That is not a thing to discover afterwards, so the Settings pane names them before asking.
+ * Nothing shares a `go` module or a rustup component, so those answer with nothing.
+ */
+export function serversSharingInstall(definition: LanguageServerDefinition): LanguageServerDefinition[] {
+  const plan = definition.install;
+  if (plan?.with !== "bun") return [];
+  const pkg = packageName(plan.packages[0] ?? "");
+  return LANGUAGE_SERVERS.filter(
+    (s) =>
+      s.id !== definition.id &&
+      s.install?.with === "bun" &&
+      packageName(s.install.packages[0] ?? "") === pkg,
+  );
+}
+
 /**
  * Directories to search, nearest first, from the file's own directory up to and
  * including the project root.
@@ -386,16 +451,67 @@ export function bundledServerEntry(
 ): string | null {
   const pkg = definition.bundledPackage;
   if (!pkg) return null;
-  let manifestPath: string;
+  try {
+    return binEntry(resolve(`${pkg}/package.json`), definition.command);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The entry script of an npm server the Install button put in PPM's own directory.
+ *
+ * Built as a path *under* `installDir` rather than resolved through `require`: Node resolution
+ * climbs out of the directory it starts in, so a stray `~/node_modules` would answer for a
+ * package PPM never installed — and whatever answers here is executed.
+ */
+export function installedServerEntry(definition: LanguageServerDefinition, installDir: string): string | null {
+  if (definition.install?.with !== "bun") return null;
+  const spec = definition.install.packages[0];
+  if (!spec) return null;
+  const pkgDir = path.join(installDir, "node_modules", ...packageName(spec).split("/"));
+  return binEntry(path.join(pkgDir, "package.json"), definition.command);
+}
+
+/**
+ * Where a compiled server the Install button built would be — PPM's own `bin` directory.
+ *
+ * That is `GOBIN` for the install, so the binary is PPM's to find and to delete, and the
+ * user's `~/go/bin` is left as they arranged it. A plain path: whether it exists is the
+ * caller's `exists()`, the same as for every other candidate.
+ */
+export function installedBinaryPath(
+  definition: LanguageServerDefinition,
+  installDir: string,
+  platform: NodeJS.Platform = process.platform,
+): string | null {
+  if (definition.install?.with !== "go") return null;
+  return path.join(installDir, "bin", platform === "win32" ? `${definition.command}.exe` : definition.command);
+}
+
+/** `typescript@5` → `typescript`, keeping a scoped package's own leading `@`. */
+export function packageName(spec: string): string {
+  const at = spec.indexOf("@", 1);
+  return at === -1 ? spec : spec.slice(0, at);
+}
+
+/**
+ * `bin[command]` from a package manifest, as an absolute path.
+ *
+ * Both callers want the package's **entry script** and not npm's `.bin` shim: that shim starts
+ * `#!/usr/bin/env node`, and someone who installed PPM with bun may have no `node` on the
+ * machine at all — measured as exit **127** with `env: 'node': No such file or directory`,
+ * after the server had already been reported as installed. The manager runs the entry with bun.
+ */
+function binEntry(manifestPath: string, command: string): string | null {
   let manifest: { bin?: string | Record<string, string> };
   try {
-    manifestPath = resolve(`${pkg}/package.json`);
     manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as typeof manifest;
   } catch {
-    return null;
+    return null; // not installed, or a manifest we cannot read
   }
   // `bin` is either a bare string — the package's own name — or a map of command to path.
-  const relative = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.[definition.command];
+  const relative = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.[command];
   if (!relative) return null;
   return path.resolve(path.dirname(manifestPath), relative);
 }

package/src/services/named-tunnel/named-tunnel-config.ts

@@ -9,6 +9,8 @@
 export type TunnelMode = "quick" | "named";
 
 export interface ResolvedTunnelConfig {
+  /** Master switch — `false` means spawn no tunnel at all, whatever `mode` says. */
+  enabled: boolean;
   mode: TunnelMode;
   hostname: string | null;
   tunnelName: string | null;
@@ -18,7 +20,7 @@ export interface ResolvedTunnelConfig {
   dismissed: boolean;
 }
 
-const QUICK: Omit<ResolvedTunnelConfig, "dismissed"> = {
+const QUICK: Omit<ResolvedTunnelConfig, "dismissed" | "enabled"> = {
   mode: "quick", hostname: null, tunnelName: null, token: null, zoneID: null, accountID: null,
 };
 
@@ -35,6 +37,9 @@ export function resolveTunnelConfig(raw: unknown): ResolvedTunnelConfig {
   }
 
   const dismissed = obj != null && typeof obj.dismissed === "boolean" ? obj.dismissed : false;
+  // Absent means a row older than the master switch, back when the tunnel was
+  // unconditional — absent is therefore on, never off.
+  const enabled = obj != null && typeof obj.enabled === "boolean" ? obj.enabled : true;
 
   // Named mode requires BOTH the stored mode flag AND all four identity fields —
   // checking fields alone would resurrect a tunnel the user explicitly disabled,
@@ -46,10 +51,11 @@ export function resolveTunnelConfig(raw: unknown): ResolvedTunnelConfig {
     nonEmptyString(obj.accountID);
 
   if (!named || obj == null) {
-    return { ...QUICK, dismissed };
+    return { ...QUICK, enabled, dismissed };
   }
 
   return {
+    enabled,
     mode: "named",
     hostname: obj.namedTunnelHostname as string,
     tunnelName: nonEmptyString(obj.namedTunnelName) ? obj.namedTunnelName : null,

package/src/services/named-tunnel/named-tunnel-setup.service.ts

@@ -159,6 +159,10 @@ async function runSetupInner(hostname: string): Promise<SetupOutcome> {
 
   broadcastGlobalEvent({ type: "tunnel:setup_step", step: "apply", message: "applying configuration" });
   configService.set("tunnel", {
+    // Carry the master switch across rather than defaulting it: configuring a
+    // domain is not consent to start sharing, and this write would otherwise
+    // silently turn a deliberately-off tunnel back on.
+    enabled: configService.get("tunnel").enabled,
     mode: "named",
     namedTunnelName: tunnelName,
     namedTunnelHostname: hostname,

package/src/services/read-lines.ts

@@ -0,0 +1,54 @@
+/**
+ * Streaming line reader for the JSONL transcripts.
+ *
+ * Its own module because two readers need it — the full message parser and the
+ * compaction scan — and having the second import it from the first would make the
+ * two files a cycle.
+ */
+
+/**
+ * Yield a file's lines without holding the file in memory.
+ *
+ * `Bun.file().text()` plus `split("\n")` costs the whole transcript twice over —
+ * 277MB resident for a 77MB file, which is what forced a cap low enough to
+ * reject real sessions. Peak here is one chunk plus one line.
+ *
+ * `fromByte` reads a tail window instead of the whole file, for the callers that
+ * have to bound what they parse. See `fullParseWindow` in
+ * `jsonl-transcript-parser.ts` for why a bound is a window rather than a refusal.
+ */
+export async function* readLines(filePath: string, fromByte = 0): AsyncGenerator<string> {
+  const decoder = new TextDecoder();
+  // Explicit reader rather than `for await` over the stream: the DOM lib's
+  // ReadableStream is not typed as async-iterable, and the `finally` is what
+  // releases it when a caller breaks early on `beforeUuid`.
+  // One byte *before* the offset, so the first line the split produces is
+  // always the tail of the record the offset fell inside — the empty string
+  // when it fell exactly on a newline. That makes the drop below unconditional
+  // instead of a boundary case, and a boundary case here silently costs a whole
+  // record rather than a fragment.
+  const file = fromByte > 0 ? Bun.file(filePath).slice(fromByte - 1) : Bun.file(filePath);
+  const reader = file.stream().getReader();
+  // A fragment is not always unparseable — the tail of one record is sometimes
+  // a complete smaller document — so it has to go by position rather than be
+  // left for `JSON.parse` to reject, or it enters as an invented message.
+  let dropPartial = fromByte > 0;
+  let buffered = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffered += decoder.decode(value, { stream: true });
+      const lines = buffered.split("\n");
+      buffered = lines.pop() ?? "";
+      for (const line of lines) {
+        if (dropPartial) { dropPartial = false; continue; }
+        yield line;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  buffered += decoder.decode();
+  if (buffered && !dropPartial) yield buffered;
+}

package/src/services/speech-to-text/whisper-catalog.ts

@@ -0,0 +1,142 @@
+/**
+ * What "install Whisper" downloads: one whisper.cpp build per platform, one
+ * speech model, and the VAD model that goes with every model.
+ *
+ * Pure and parameterised so the whole matrix is unit-testable without touching
+ * `process.*` or the network. Every entry is pinned by tag/revision AND by
+ * SHA-256, because this code downloads an executable onto the user's machine.
+ *
+ * The VAD model is not optional. Whisper invents speech out of silence, and in
+ * Vietnamese it invents the same YouTube outro every time — six seconds of
+ * digital silence transcribed as "Hãy subscribe cho kênh Ghiền Mì Gõ Để không
+ * bỏ lỡ những video hấp dẫn" on both `small` and `large-v3-turbo`, and pink
+ * noise as "Cảm ơn các bạn đã theo dõi và hẹn gặp lại." With Silero VAD in
+ * front, both come back empty (and in 0.3s instead of seconds).
+ */
+
+/** whisper.cpp release that the prebuilt binaries come from. */
+export const WHISPER_BUILD = "b5130";
+/** Whisper version inside that build, for display only. */
+export const WHISPER_VERSION = "1.9.4";
+
+const RELEASE_BASE = `https://github.com/ggml-org/whisper.cpp/releases/download/${WHISPER_BUILD}`;
+
+/** Pinned commits of the Hugging Face repos the models are fetched from. */
+const MODEL_REPO_REV = "5359861c739e955e79d9a303bcbc70fb988958b1";
+const VAD_REPO_REV = "9ffd54a1e1ee413ddf265af9913beaf518d1639b";
+
+export interface WhisperAsset {
+  /** Archive file name as published in the release. */
+  file: string;
+  url: string;
+  sha256: string;
+  ext: "tar.gz" | "zip";
+}
+
+/**
+ * Prebuilt whisper.cpp per platform.
+ *
+ * macOS is deliberately absent: the release ships an xcframework (a library for
+ * Swift apps), never a `whisper-cli`, so there is nothing to download and
+ * unpack. A Mac uses Homebrew's `whisper.cpp` formula instead — see
+ * `MACOS_INSTALL_HINT` — and PPM then finds `whisper-cli` on PATH.
+ */
+const ASSETS: Record<string, WhisperAsset> = {
+  "linux-x64": {
+    file: "whisper-bin-ubuntu-x64.tar.gz",
+    url: `${RELEASE_BASE}/whisper-bin-ubuntu-x64.tar.gz`,
+    sha256: "53e7fd8b5764edad916b8848dd0af6abb1ff1d3b86c899e79c78652412536c32",
+    ext: "tar.gz",
+  },
+  "linux-arm64": {
+    file: "whisper-bin-ubuntu-arm64.tar.gz",
+    url: `${RELEASE_BASE}/whisper-bin-ubuntu-arm64.tar.gz`,
+    sha256: "93532a0e3777f26f041ffa358ee77dd88b1a33a86847c1990745327ff335a5d6",
+    ext: "tar.gz",
+  },
+  "win32-x64": {
+    file: "whisper-bin-x64.zip",
+    url: `${RELEASE_BASE}/whisper-bin-x64.zip`,
+    sha256: "f9ec6c52a2e949b62ab51fa21d0d497958f9e41c3010c157c4e42932d5316f3c",
+    ext: "zip",
+  },
+  "win32-arm64": {
+    file: "whisper-bin-win-cpu-arm64.zip",
+    url: `${RELEASE_BASE}/whisper-bin-win-cpu-arm64.zip`,
+    sha256: "799543b926ab5b6c2d60cab269a2092e0ae8d27820e9e15429e59de3699546fc",
+    ext: "zip",
+  },
+};
+
+export const MACOS_INSTALL_HINT = "brew install whisper.cpp";
+
+/** The published build for a platform/arch pair, or null when there is none. */
+export function whisperAssetFor(platform: NodeJS.Platform, arch: string): WhisperAsset | null {
+  return ASSETS[`${platform}-${arch}`] ?? null;
+}
+
+export interface WhisperModel {
+  id: string;
+  /** File name in the Hugging Face repo, and on disk. */
+  file: string;
+  label: string;
+  /** One line under the label in Settings. */
+  note: string;
+  bytes: number;
+  sha256: string;
+}
+
+/**
+ * Three rungs, measured on a 10s Vietnamese clip (i9-12900K, 16 threads):
+ * `base` 0.9s but "sửa giúp" came back "sửa dụp"; `small` 2.2s and readable;
+ * `large-v3-turbo` 5.5s and the only one that kept English identifiers
+ * ("handle ... toggle ... message input") intact. Quantized weights, since a
+ * q5 file is a third of the size for no accuracy difference anyone dictating a
+ * chat message would notice.
+ */
+export const WHISPER_MODELS: WhisperModel[] = [
+  {
+    id: "base-q5_1",
+    file: "ggml-base-q5_1.bin",
+    label: "Base",
+    note: "Fastest, weakest — usable for English, rough in Vietnamese",
+    bytes: 59_707_625,
+    sha256: "422f1ae452ade6f30a004d7e5c6a43195e4433bc370bf23fac9cc591f01a8898",
+  },
+  {
+    id: "small-q5_1",
+    file: "ggml-small-q5_1.bin",
+    label: "Small",
+    note: "Middle ground — readable Vietnamese, garbles English words",
+    bytes: 190_085_487,
+    sha256: "ae85e4a935d7a567bd102fe55afc16bb595bdb618e11b2fc7591bc08120411bb",
+  },
+  {
+    id: "large-v3-turbo-q5_0",
+    file: "ggml-large-v3-turbo-q5_0.bin",
+    label: "Large v3 Turbo",
+    note: "Best Vietnamese, keeps English terms — a few seconds per sentence",
+    bytes: 574_041_195,
+    sha256: "394221709cd5ad1f40c46e6031ca61bce88931e6e088c188294c6d5a55ffa7e2",
+  },
+];
+
+export const DEFAULT_MODEL_ID = "large-v3-turbo-q5_0";
+
+export const VAD_MODEL = {
+  file: "ggml-silero-v5.1.2.bin",
+  bytes: 885_098,
+  sha256: "29940d98d42b91fbd05ce489f3ecf7c72f0a42f027e4875919a28fb4c04ea2cf",
+};
+
+export function modelById(id: string): WhisperModel | null {
+  return WHISPER_MODELS.find((m) => m.id === id) ?? null;
+}
+
+export function modelUrl(model: WhisperModel): string {
+  return `https://huggingface.co/ggerganov/whisper.cpp/resolve/${MODEL_REPO_REV}/${model.file}`;
+}
+
+export function vadModelUrl(): string {
+  return `https://huggingface.co/ggml-org/whisper-vad/resolve/${VAD_REPO_REV}/${VAD_MODEL.file}`;
+}

package/src/services/speech-to-text/whisper-download.ts

@@ -0,0 +1,113 @@
+/**
+ * Streaming download with a SHA-256 gate.
+ *
+ * A model is 574 MB, so it is hashed while it streams rather than read back
+ * afterwards, and it lands on a `.part` file that is only renamed once the hash
+ * matches: an interrupted or tampered download can never be mistaken for an
+ * installed one, and a retry starts clean.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, renameSync, rmSync } from "node:fs";
+import { dirname } from "node:path";
+
+export type FetchFn = typeof fetch;
+
+export interface DownloadOptions {
+  url: string;
+  dest: string;
+  /** Lowercase hex. The download is discarded when the bytes hash to anything else. */
+  sha256: string;
+  /** Called as bytes arrive; `total` is 0 when the server sends no Content-Length. */
+  onProgress?: (received: number, total: number) => void;
+  fetchFn?: FetchFn;
+  signal?: AbortSignal;
+}
+
+/**
+ * How long the transfer may produce no bytes at all before it is abandoned.
+ *
+ * Idle rather than wall-clock: the largest model here is 574 MB, and any total-time
+ * bound that a slow line can exceed would abort a download that was working. What is
+ * never legitimate is silence — a half-open socket after a dropped wifi link or a
+ * tunnel that went away never errors and never yields, so without this the `for await`
+ * below simply never returns and the install never settles.
+ */
+const STALL_TIMEOUT_MS = 60_000;
+
+export async function downloadVerified(opts: DownloadOptions): Promise<void> {
+  const { url, dest, sha256, onProgress, signal } = opts;
+  const fetchFn = opts.fetchFn ?? fetch;
+  const part = `${dest}.part`;
+
+  mkdirSync(dirname(dest), { recursive: true });
+  rmSync(part, { force: true });
+
+  // The caller's signal and the stall timer both have to reach the body stream, and
+  // `fetch` takes one signal — so an internal controller carries both.
+  const stall = new AbortController();
+  const forwardAbort = () => stall.abort(signal?.reason);
+  signal?.addEventListener("abort", forwardAbort, { once: true });
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const armStallTimer = (): void => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(
+      () => stall.abort(new Error(`download stalled: no bytes for ${STALL_TIMEOUT_MS}ms (${url})`)),
+      STALL_TIMEOUT_MS,
+    );
+    timer.unref?.();
+  };
+  const disarm = (): void => {
+    if (timer) clearTimeout(timer);
+    timer = null;
+    signal?.removeEventListener("abort", forwardAbort);
+  };
+
+  let res: Response;
+  armStallTimer();
+  try {
+    res = await fetchFn(url, { redirect: "follow", signal: stall.signal });
+  } catch (e) {
+    disarm();
+    throw stall.signal.aborted && stall.signal.reason instanceof Error ? stall.signal.reason : e;
+  }
+  if (!res.ok) { disarm(); throw new Error(`download failed: HTTP ${res.status} (${url})`); }
+  if (!res.body) { disarm(); throw new Error(`download failed: empty body (${url})`); }
+
+  const total = Number(res.headers.get("content-length") ?? 0) || 0;
+  const hash = createHash("sha256");
+  const sink = Bun.file(part).writer();
+  let received = 0;
+
+  try {
+    for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
+      armStallTimer();
+      hash.update(chunk);
+      sink.write(chunk);
+      received += chunk.byteLength;
+      onProgress?.(received, total);
+    }
+    await sink.end();
+    disarm();
+  } catch (e) {
+    disarm();
+    try {
+      await sink.end();
+    } catch {
+      // Sink already torn down by the failure itself.
+    }
+    rmSync(part, { force: true });
+    // An abort raised by the stall timer carries the reason worth reporting; the
+    // stream's own `AbortError` says only that somebody cancelled.
+    throw stall.signal.aborted && stall.signal.reason instanceof Error ? stall.signal.reason : e;
+  }
+
+  const actual = hash.digest("hex");
+  if (actual !== sha256.toLowerCase()) {
+    rmSync(part, { force: true });
+    throw new Error(`checksum mismatch for ${url}: expected ${sha256}, got ${actual}`);
+  }
+
+  // Windows refuses a rename onto an existing file, so clear the target first.
+  rmSync(dest, { force: true });
+  renameSync(part, dest);
+}

package/src/services/speech-to-text/whisper-hallucinations.ts

@@ -0,0 +1,51 @@
+/**
+ * Sentences Whisper invents when it is handed audio with no speech in it.
+ *
+ * The model was trained on YouTube subtitles, so the likeliest continuation of
+ * "a Vietnamese clip with nothing being said" is that channel's sign-off — and
+ * it is not a rare edge case: with `--vad` off, *every* non-speech clip
+ * measured on large-v3-turbo (digital silence, white noise at four levels,
+ * 50 Hz hum, a 440 Hz tone, brown noise, keyboard clicks, a cough, a breath)
+ * came back as the same one sentence, byte for byte:
+ *
+ *     silence/noise/hum/tone/typing/cough  →  "Hãy subscribe cho kênh Ghiền Mì
+ *                                              Gõ Để không bỏ lỡ những video hấp dẫn"
+ *     room tone                            →  "Cảm ơn các bạn đã theo dõi và hẹn gặp lại."
+ *
+ * The VAD model is what normally stops this (those same clips come back empty
+ * with it on), so this list is the second line of defence for the audio VAD
+ * does let through — a fan, a distant TV, a word spoken too far from the mic.
+ * It is deliberately short and measured rather than guessed: add a sentence
+ * here only after seeing this model produce it from a clip with no speech.
+ */
+
+/** Same shape as the list: lowercased, punctuation dropped, spaces collapsed. */
+function normalize(line: string): string {
+  return line
+    .toLowerCase()
+    .replace(/[.,!?;:"'`*\-_()[\]…]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const INVENTED = [
+  "Hãy subscribe cho kênh Ghiền Mì Gõ Để không bỏ lỡ những video hấp dẫn",
+  "Cảm ơn các bạn đã theo dõi và hẹn gặp lại.",
+].map(normalize);
+
+/**
+ * The channel name is the fingerprint: the sign-off comes back with small
+ * wording changes, and nobody dictating into a chat box says it at all.
+ */
+const FINGERPRINT = normalize("Ghiền Mì Gõ");
+
+/**
+ * True for a whole segment the model made up. Whole lines only — `-nt` prints
+ * one line per segment, so dropping a line drops exactly the invented
+ * sentence and leaves the real ones either side of it alone.
+ */
+export function isInventedLine(line: string): boolean {
+  const normalized = normalize(line);
+  if (normalized.length === 0) return false;
+  return INVENTED.includes(normalized) || normalized.includes(FINGERPRINT);
+}