fix(hyperframes-media): surface the real reason a TTS line failed [P2] (#1999)

* fix(hyperframes-media): surface the real reason a TTS line failed

synthesizeHeygen() swallowed every failure into a bare { ok:false }: a thrown
HTTP error (e.g. 402 plan_upgrade_required from heygenJSON) was caught and
discarded, a missing audio_url / failed audio fetch / failed transcode all
returned nothing. audio.mjs then logged 'TTS failed — omitted' for every line
with zero detail, so the actual cause took a hand-rolled repro to find.

Each failure path now returns an { error } string (the caught message, the HTTP
status, or the specific stage that failed), and audio.mjs appends it to the
anomaly. The subprocess providers (elevenlabs/kokoro) get the same treatment via
a shared synthResult() helper. synthesizeHeygen takes an injectable deps arg so
the failure paths are unit-tested (thrown 402, non-ok fetch, missing audio_url).

* fix(media-use): report wav transcode failures accurately

* chore: regenerate skills manifest

skills/media-use/audio/scripts/lib/tts.test.mjs

@@ -3,7 +3,13 @@ import assert from "node:assert/strict";
 import { mkdtempSync, writeFileSync, chmodSync, rmSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
-import { parseFfmpegDurationBanner, ffprobeDuration, synthesizeOne } from "./tts.mjs";
+import {
+  parseFfmpegDurationBanner,
+  ffprobeDuration,
+  synthesizeOne,
+  synthesizeHeygen,
+  synthResult,
+} from "./tts.mjs";
 
 test("parseFfmpegDurationBanner reads ffmpeg's stderr Duration line", () => {
   const stderr = [
@@ -87,3 +93,65 @@ test("synthesizeOne(elevenlabs) creates the output dir before writing", async ()
     rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test("synthesizeHeygen surfaces a thrown HTTP error (e.g. 402) instead of swallowing it", async () => {
+  const res = await synthesizeHeygen(
+    { text: "hi", voiceId: "v1", lang: "en", speed: 1, wavAbs: "/tmp/x.wav" },
+    {
+      heygenAuthHeaders: () => ({}),
+      heygenJSON: async () => {
+        throw new Error("HeyGen POST /voices/speech → HTTP 402\nplan_upgrade_required");
+      },
+    },
+  );
+  assert.equal(res.ok, false);
+  assert.match(res.error, /402/);
+  assert.match(res.error, /plan_upgrade_required/);
+});
+
+test("synthesizeHeygen surfaces a failed audio_url fetch with its status", async () => {
+  const res = await synthesizeHeygen(
+    { text: "hi", voiceId: "v1", lang: "en", speed: 1, wavAbs: "/tmp/x.wav" },
+    {
+      heygenAuthHeaders: () => ({}),
+      heygenJSON: async () => ({ data: { audio_url: "http://audio.example/x" } }),
+      fetch: async () => ({ ok: false, status: 403 }),
+    },
+  );
+  assert.equal(res.ok, false);
+  assert.match(res.error, /HTTP 403/);
+});
+
+test("synthesizeHeygen reports a missing audio_url", async () => {
+  const res = await synthesizeHeygen(
+    { text: "hi", voiceId: "v1", lang: "en", speed: 1, wavAbs: "/tmp/x.wav" },
+    { heygenAuthHeaders: () => ({}), heygenJSON: async () => ({}) },
+  );
+  assert.equal(res.ok, false);
+  assert.match(res.error, /no audio_url/);
+});
+
+test("synthesizeHeygen reports wav transcode failures", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "hf-tts-test-"));
+  try {
+    const res = await synthesizeHeygen(
+      { text: "hi", voiceId: "v1", lang: "en", speed: 1, wavAbs: join(dir, "voice.wav") },
+      {
+        heygenAuthHeaders: () => ({}),
+        heygenJSON: async () => ({ data: { audio_url: "http://audio.example/x" } }),
+        fetch: async () => ({ ok: true, status: 200, arrayBuffer: async () => new ArrayBuffer(0) }),
+        transcodeToWav: () => false,
+      },
+    );
+    assert.equal(res.ok, false);
+    assert.equal(res.error, "wav transcode failed (ffmpeg)");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("synthResult names a non-zero subprocess exit", () => {
+  const res = synthResult({ status: 2 }, "/tmp/none.wav", "kokoro (npx hyperframes tts)");
+  assert.equal(res.ok, false);
+  assert.match(res.error, /kokoro .* exited with status 2/);
+});