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.mjs

@@ -225,9 +225,10 @@ save(audio, sys.argv[3])
 `;
 
 // ── synthesize one line ───────────────────────────────────────────────────────
-// Writes wav at wavAbs. Returns { ok, words } — words is the raw
+// Writes wav at wavAbs. Returns { ok, words, error } — words is the raw
 // [{text,start,end}] array for HeyGen (native), or null for ElevenLabs/Kokoro
-// (caller must transcribeWav). Never throws; failures return { ok:false }.
+// (caller must transcribeWav). Never throws; failures return { ok:false, error }
+// where `error` states WHY (so the caller can surface it, not a bare "TTS failed").
 export async function synthesizeOne({
   provider,
   text,
@@ -259,34 +260,61 @@ export async function synthesizeOne({
       wavAbs,
     ]);
     const r = await spawnP(cmd, args, {});
-    return { ok: r.status === 0 && existsSync(wavAbs), words: null };
+    return synthResult(r, wavAbs, "elevenlabs (python)");
   }
   // kokoro — via the published CLI; --output is relative to the project dir.
   const wavRel = relTo(hyperframesDir, wavAbs);
   const args = ["hyperframes", "tts", writeTmpText(text), "--voice", voiceId, "--output", wavRel];
   if (lang !== "en") args.push("--lang", lang);
   const r = await spawnP("npx", args, { cwd: hyperframesDir });
-  return { ok: r.status === 0 && existsSync(wavAbs), words: null };
+  return synthResult(r, wavAbs, "kokoro (npx hyperframes tts)");
 }
 
-async function synthesizeHeygen({ text, voiceId, lang, speed, wavAbs }) {
+// Shape a spawn result into { ok, words, error }, naming why on failure so the
+// caller surfaces it instead of a bare "TTS failed".
+export function synthResult(r, wavAbs, label) {
+  if (r.status === 0 && existsSync(wavAbs)) return { ok: true, words: null };
+  const why =
+    r.status !== 0 ? `${label} exited with status ${r.status}` : `${label} produced no wav file`;
+  return { ok: false, words: null, error: why };
+}
+
+// `deps` is injectable for tests; production uses the real network/ffmpeg impls.
+// Every failure path returns an `error` string so the caller can surface WHY a
+// line was dropped instead of the bare "TTS failed" that hid the real cause
+// (e.g. an HTTP 402 plan_upgrade_required thrown by heygenJSON was swallowed).
+export async function synthesizeHeygen({ text, voiceId, lang, speed, wavAbs }, deps = {}) {
+  const requestJSON = deps.heygenJSON ?? heygenJSON;
+  const authHeaders = deps.heygenAuthHeaders ?? heygenAuthHeaders;
+  const fetchImpl = deps.fetch ?? fetch;
+  const transcode = deps.transcodeToWav ?? transcodeToWav;
   try {
     const body = { text, voice_id: voiceId, speed };
     if (lang !== "en") body.language = lang;
-    const payload = await heygenJSON(`/voices/speech`, {
+    const payload = await requestJSON(`/voices/speech`, {
       method: "POST",
-      headers: heygenAuthHeaders(),
+      headers: authHeaders(),
       body,
     });
     const inner = payload.data ?? payload;
-    if (!inner.audio_url) return { ok: false, words: null };
-    const res = await fetch(inner.audio_url);
-    if (!res.ok) return { ok: false, words: null };
+    if (!inner.audio_url) {
+      return { ok: false, words: null, error: "HeyGen /voices/speech returned no audio_url" };
+    }
+    const res = await fetchImpl(inner.audio_url);
+    if (!res.ok) {
+      return { ok: false, words: null, error: `audio_url fetch failed: HTTP ${res.status}` };
+    }
     const bytes = Buffer.from(await res.arrayBuffer());
     // .wav output → transcode to 44.1k mono; .mp3 → raw bytes (no ffmpeg). The
     // engine always asks for .wav; the standalone heygen-tts CLI may ask for .mp3.
     if (wavAbs.endsWith(".wav")) {
-      if (!transcodeToWav(bytes, wavAbs)) return { ok: false, words: null };
+      if (!transcode(bytes, wavAbs)) {
+        return {
+          ok: false,
+          words: null,
+          error: "wav transcode failed (ffmpeg)",
+        };
+      }
     } else {
       mkdirSync(dirname(wavAbs), { recursive: true });
       writeFileSync(wavAbs, bytes);
@@ -298,8 +326,8 @@ async function synthesizeHeygen({ text, voiceId, lang, speed, wavAbs }) {
           .map((w) => ({ text: w.word, start: w.start, end: w.end }))
       : [];
     return { ok: true, words };
-  } catch {
-    return { ok: false, words: null };
+  } catch (e) {
+    return { ok: false, words: null, error: e?.message ? String(e.message) : String(e) };
   }
 }