hyperframes 0.8.58 → 0.8.59

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

@@ -0,0 +1,158 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import {
+  resolveNpxCliFromNpmExecPath,
+  resolveNpxCliPath,
+  resolveSpawnCommand,
+  spawnP,
+  _resetNpxResolutionWarnForTests,
+} from "./tts.mjs";
+
+// Regression: on Windows, npx resolves to npx.cmd, which spawn() cannot exec
+// without shell:true — it fails ENOENT, silently swallowed as ok:false by the
+// caller. spawnP takes injectable platform/spawnFn params so this doesn't
+// need to touch the real process.platform or mock node:child_process (whose
+// ESM exports are non-configurable).
+function fakeSpawn(captured) {
+  return (cmd, args, opts) => {
+    captured.push({ cmd, args, opts });
+    const p = new EventEmitter();
+    setImmediate(() => p.emit("exit", 0));
+    return p;
+  };
+}
+
+const envWithNpxCli = {
+  npm_execpath: "/opt/node/lib/node_modules/npm/bin/npm-cli.js",
+  npm_node_execpath: "/opt/node/bin/node",
+};
+const npxCliPath = "/opt/node/lib/node_modules/npm/bin/npx-cli.js";
+const pathExists = (path) => path === npxCliPath;
+
+test("resolveNpxCliFromNpmExecPath finds npx-cli next to npm-cli", () => {
+  assert.equal(resolveNpxCliFromNpmExecPath(envWithNpxCli.npm_execpath, pathExists), npxCliPath);
+});
+
+test("resolveNpxCliPath finds npx-cli beside node when npm_execpath is unset", () => {
+  const node = "C:/Program Files/nodejs/node.exe";
+  const expected = "C:/Program Files/nodejs/node_modules/npm/bin/npx-cli.js";
+  assert.equal(
+    resolveNpxCliPath(undefined, node, (path) => path === expected),
+    expected,
+  );
+});
+
+test("resolveSpawnCommand routes npx through node+npx-cli on win32 without shell:true", () => {
+  const resolved = resolveSpawnCommand(
+    "npx",
+    ["hyperframes", "tts", "C:\\Users\\Test User\\line.txt", "--voice", "am_michael"],
+    {},
+    "win32",
+    envWithNpxCli,
+    pathExists,
+  );
+  assert.ok(resolved);
+  assert.equal(resolved.cmd, envWithNpxCli.npm_node_execpath);
+  assert.deepEqual(resolved.args, [
+    npxCliPath,
+    "hyperframes",
+    "tts",
+    "C:\\Users\\Test User\\line.txt",
+    "--voice",
+    "am_michael",
+  ]);
+  assert.equal(resolved.opts.shell, undefined);
+});
+
+test("resolveSpawnCommand preserves Windows npx shell metacharacters as argv data", () => {
+  const resolved = resolveSpawnCommand(
+    "npx",
+    ["hyperframes", "tts", "hello & calc"],
+    {},
+    "win32",
+    envWithNpxCli,
+    pathExists,
+  );
+  assert.ok(resolved);
+  assert.deepEqual(resolved.args, [npxCliPath, "hyperframes", "tts", "hello & calc"]);
+});
+
+test("spawnP uses the resolved node+npx-cli command for npx on win32", async () => {
+  const captured = [];
+  await spawnP(
+    "npx",
+    ["hyperframes", "tts"],
+    {},
+    "win32",
+    fakeSpawn(captured),
+    envWithNpxCli,
+    pathExists,
+  );
+  assert.equal(captured.length, 1);
+  assert.equal(captured[0].cmd, envWithNpxCli.npm_node_execpath);
+  assert.deepEqual(captured[0].args, [npxCliPath, "hyperframes", "tts"]);
+  assert.equal(captured[0].opts.shell, undefined);
+});
+
+test("spawnP does not enable shell for npx on darwin/linux", async () => {
+  const captured = [];
+  await spawnP("npx", ["hyperframes", "tts"], {}, "darwin", fakeSpawn(captured));
+  assert.equal(captured[0].cmd, "npx");
+  assert.deepEqual(captured[0].args, ["hyperframes", "tts"]);
+  assert.equal(captured[0].opts.shell, undefined);
+});
+
+test("spawnP does not enable shell for non-npx commands even on win32", async () => {
+  const captured = [];
+  await spawnP("python3", ["-c", "pass"], {}, "win32", fakeSpawn(captured));
+  assert.equal(captured[0].cmd, "python3");
+  assert.deepEqual(captured[0].args, ["-c", "pass"]);
+  assert.equal(captured[0].opts.shell, undefined);
+});
+
+test("spawnP resolves npx beside node when npm_execpath is unset on win32", async () => {
+  _resetNpxResolutionWarnForTests();
+  const captured = [];
+  const node = "C:/Program Files/nodejs/node.exe";
+  const npxCli = "C:/Program Files/nodejs/node_modules/npm/bin/npx-cli.js";
+  const result = await spawnP(
+    "npx",
+    ["hyperframes", "tts"],
+    {},
+    "win32",
+    fakeSpawn(captured),
+    { npm_node_execpath: node },
+    (path) => path === npxCli,
+  );
+  assert.equal(result.status, 0);
+  assert.equal(captured.length, 1);
+  assert.equal(captured[0].cmd, node);
+  assert.deepEqual(captured[0].args, [npxCli, "hyperframes", "tts"]);
+});
+
+test("spawnP warns once with an accurate diagnostic when neither npx path exists", async () => {
+  _resetNpxResolutionWarnForTests();
+  const errors = [];
+  const originalError = console.error;
+  console.error = (message) => errors.push(String(message));
+  try {
+    const env = { npm_execpath: "C:/missing/npm-cli.js", npm_node_execpath: "C:/node/node.exe" };
+    const missing = () => false;
+    assert.equal(
+      (await spawnP("npx", ["hyperframes", "tts"], {}, "win32", fakeSpawn([]), env, missing))
+        .status,
+      -1,
+    );
+    assert.equal(
+      (await spawnP("npx", ["hyperframes", "tts"], {}, "win32", fakeSpawn([]), env, missing))
+        .status,
+      -1,
+    );
+  } finally {
+    console.error = originalError;
+  }
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /npm_execpath \(C:\/missing\/npm-cli\.js\)/);
+  assert.doesNotMatch(errors[0], /npm_execpath is not set/);
+});

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

@@ -0,0 +1,157 @@
+import { test } from "node:test";
+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,
+  synthesizeHeygen,
+  synthResult,
+} from "./tts.mjs";
+
+test("parseFfmpegDurationBanner reads ffmpeg's stderr Duration line", () => {
+  const stderr = [
+    "ffmpeg version 6.0",
+    "Input #0, wav, from 'a.wav':",
+    "  Duration: 00:00:03.42, bitrate: 705 kb/s",
+    "At least one output file must be specified",
+  ].join("\n");
+  assert.equal(parseFfmpegDurationBanner(stderr), 3.42);
+});
+
+test("parseFfmpegDurationBanner handles an hours component", () => {
+  const stderr = "  Duration: 01:02:03.50, start: 0.000000, bitrate: 128 kb/s";
+  assert.equal(parseFfmpegDurationBanner(stderr), 3723.5);
+});
+
+test("parseFfmpegDurationBanner returns NaN when there is no Duration line", () => {
+  assert.ok(Number.isNaN(parseFfmpegDurationBanner("ffmpeg: command not found")));
+  assert.ok(Number.isNaN(parseFfmpegDurationBanner("")));
+  assert.ok(Number.isNaN(parseFfmpegDurationBanner(undefined)));
+});
+
+// Regression for the actual bug: ffprobeDuration used to collapse "ffprobe
+// binary is missing" (ENOENT — the "essentials"-style Windows ffmpeg build
+// with no ffprobe.exe) and "file is genuinely unreadable" into the same NaN,
+// giving audio.mjs no way to tell "measure differently" from "give up".
+//
+// Builds an isolated PATH containing only a fake `ffmpeg` stub (no `ffprobe`
+// at all) so ffprobeDuration's spawnSync("ffprobe", ...) call ENOENTs for
+// real, then verifies it recovers the duration via the ffmpeg fallback
+// instead of returning NaN.
+test("ffprobeDuration falls back to ffmpeg when the ffprobe binary itself is missing", () => {
+  const dir = mkdtempSync(join(tmpdir(), "tts-ffprobe-fallback-"));
+  const fakeFfmpeg = join(dir, "ffmpeg");
+  writeFileSync(
+    fakeFfmpeg,
+    "#!/bin/sh\necho 'Duration: 00:00:02.50, start: 0.000000, bitrate: 128 kb/s' 1>&2\nexit 1\n",
+  );
+  chmodSync(fakeFfmpeg, 0o755);
+  const originalPath = process.env.PATH;
+  try {
+    process.env.PATH = dir; // only the fake ffmpeg resolves; no real ffprobe on this PATH
+    assert.equal(ffprobeDuration("/does/not/matter.wav"), 2.5);
+  } finally {
+    process.env.PATH = originalPath;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("ffprobeDuration returns NaN when neither ffprobe nor ffmpeg resolve", () => {
+  const dir = mkdtempSync(join(tmpdir(), "tts-no-binaries-"));
+  const originalPath = process.env.PATH;
+  try {
+    process.env.PATH = dir; // empty directory — nothing resolves
+    assert.ok(Number.isNaN(ffprobeDuration("/does/not/matter.wav")));
+  } finally {
+    process.env.PATH = originalPath;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("synthesizeOne(elevenlabs) creates the output dir before writing", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "tts-el-mkdir-"));
+  const wavAbs = join(dir, "assets", "voice", "line-0.wav"); // nested, not yet created
+  const savedKey = process.env.ELEVENLABS_API_KEY;
+  try {
+    // Unset the key so the Python side fails fast — the mkdir must run before
+    // the spawn regardless, which is what this guards.
+    delete process.env.ELEVENLABS_API_KEY;
+    await synthesizeOne({
+      provider: "elevenlabs",
+      text: "hi",
+      voiceId: "v",
+      wavAbs,
+      hyperframesDir: dir,
+    });
+    assert.ok(existsSync(dirname(wavAbs)), "output directory should be created");
+  } finally {
+    if (savedKey === undefined) delete process.env.ELEVENLABS_API_KEY;
+    else process.env.ELEVENLABS_API_KEY = savedKey;
+    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/);
+});

package/dist/skills/media-use/audio/scripts/lyria-recipe.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Generate BGM using Google Lyria RealTime API.
+
+Usage:
+    python lyria-recipe.py --output <path> --duration <seconds> [tuning flags]
+
+Requires:
+    $GOOGLE_API_KEY or $GEMINI_API_KEY environment variable (treated as aliases).
+    pip install google-genai python-dotenv. audio.mjs Step 4b installs these on
+    demand when a key is set but google.genai is not importable; if that install
+    fails it falls back to local MusicGen rather than leaving the video with no BGM.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+import wave
+from pathlib import Path
+
+# Windows sizes stdio to the ANSI code page (cp1252). These scripts emit UTF-8 on
+# every platform; say so rather than depending on the console's code page. Carry
+# `errors` across: reconfigure() resets it to "strict", and CPython deliberately gives
+# stderr "backslashreplace" so the diagnostic path can never itself raise.
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        _stream.reconfigure(encoding="utf-8", errors=_stream.errors)
+
+DEFAULT_PROMPT = "Uplifting corporate tech, bright and modern, gentle piano with synth pads"
+SAMPLE_RATE = 48000
+CHANNELS = 2
+SAMPLE_WIDTH = 2  # 16-bit
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Generate BGM via Google Lyria RealTime.")
+    p.add_argument("--output", required=True, help="Output WAV path.")
+    p.add_argument("--duration", type=float, required=True, help="Target duration in seconds.")
+    p.add_argument("--prompt", default=DEFAULT_PROMPT, help="Mood / instrumentation prompt.")
+    p.add_argument("--negative-prompt", default=None, help="Styles to exclude (optional).")
+    p.add_argument("--bpm", type=int, default=110)
+    p.add_argument("--brightness", type=float, default=0.8, help="0-1, higher = brighter mood.")
+    p.add_argument("--density", type=float, default=0.5, help="0-1, higher = fuller mix.")
+    p.add_argument(
+        "--scale",
+        default="MAJOR",
+        help="MAJOR / MINOR / PENTATONIC / etc. — see google.genai.types.Scale. Pass empty string for none.",
+    )
+    return p.parse_args()
+
+
+async def generate_bgm(args: argparse.Namespace) -> dict:
+    from google import genai
+    from google.genai import types
+
+    api_key = os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY") or ""
+    if not api_key:
+        raise RuntimeError("Neither GOOGLE_API_KEY nor GEMINI_API_KEY is set.")
+
+    client = genai.Client(
+        api_key=api_key,
+        http_options={"api_version": "v1alpha"},
+    )
+
+    out_path = Path(args.output)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    target_bytes = int(args.duration * SAMPLE_RATE * CHANNELS * SAMPLE_WIDTH)
+
+    cfg: dict = {"bpm": args.bpm, "temperature": 1.0}
+    if args.density is not None:
+        cfg["density"] = args.density
+    if args.brightness is not None:
+        cfg["brightness"] = args.brightness
+    if args.scale:
+        scale_enum = getattr(types.Scale, args.scale, None)
+        if scale_enum:
+            cfg["scale"] = scale_enum
+
+    prompts = [types.WeightedPrompt(text=args.prompt, weight=1.0)]
+    if args.negative_prompt:
+        prompts.append(types.WeightedPrompt(text=args.negative_prompt, weight=-1.0))
+
+    buf = bytearray()
+    timeout = args.duration + 8
+
+    async with client.aio.live.music.connect(
+        model="models/lyria-realtime-exp",
+    ) as session:
+        await session.set_weighted_prompts(prompts=prompts)
+        await session.set_music_generation_config(
+            config=types.LiveMusicGenerationConfig(**cfg),
+        )
+        await session.play()
+
+        async def collect():
+            while len(buf) < target_bytes:
+                async for msg in session.receive():
+                    sc = msg.server_content
+                    if sc and sc.audio_chunks:
+                        for chunk in sc.audio_chunks:
+                            buf.extend(chunk.data)
+                            if len(buf) >= target_bytes:
+                                return
+                await asyncio.sleep(1e-6)
+
+        try:
+            await asyncio.wait_for(collect(), timeout=timeout)
+        except TimeoutError:
+            print(f"Timeout after {timeout:.0f}s, collected {len(buf)} bytes", file=sys.stderr)
+
+    audio = bytes(buf[:target_bytes])
+    with wave.open(str(out_path), "wb") as wf:
+        wf.setnchannels(CHANNELS)
+        wf.setsampwidth(SAMPLE_WIDTH)
+        wf.setframerate(SAMPLE_RATE)
+        wf.writeframes(audio)
+
+    actual_duration = len(audio) / (SAMPLE_RATE * CHANNELS * SAMPLE_WIDTH)
+    print(f"BGM: {out_path} ({actual_duration:.2f}s)")
+    return {"file": str(out_path), "duration_sec": round(actual_duration, 2)}
+
+
+def main() -> None:
+    args = parse_args()
+    try:
+        asyncio.run(generate_bgm(args))
+    except RuntimeError as exc:
+        print(f"BGM generation failed: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/dist/skills/media-use/audio/scripts/wait-bgm.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// Phase 4c pre-assemble helper — wait for detached BGM, then write status.
+//
+// audio.mjs may launch Lyria / MusicGen in a detached process so voice work can
+// keep moving. Before assemble-index.mjs decides whether to emit the BGM audio
+// track, this script gives the background renderer a bounded chance to finish
+// and converts log/process state into a small bgm_status.json file.
+//
+// Always exits 0 for normal pipeline use: missing/failed BGM should not block a
+// voice/captions/SFX render. Structural invocation errors still exit 1.
+//
+// Usage:
+//   node wait-bgm.mjs --audio-meta ./audio_meta.json --hyperframes . \
+//     [--timeout-ms 120000] [--interval-ms 2000] [--out ./bgm_status.json]
+
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const argv = process.argv.slice(2);
+const flag = (name, def) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : def;
+};
+
+function die(msg) {
+  console.error(`✗ wait-bgm.mjs: ${msg}`);
+  process.exit(1);
+}
+
+const audioMetaPath = resolve(flag("audio-meta", "./audio_meta.json"));
+const hyperframesDir = resolve(flag("hyperframes", "."));
+const outPath = resolve(flag("out", join(hyperframesDir, "bgm_status.json")));
+const timeoutMs = Math.max(0, Number(flag("timeout-ms", "120000")) || 0);
+const intervalMs = Math.max(250, Number(flag("interval-ms", "2000")) || 2000);
+
+function sleep(ms) {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+
+function isProcessAlive(pid) {
+  if (!pid || !Number.isFinite(Number(pid))) return false;
+  try {
+    process.kill(Number(pid), 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readTail(path, maxChars = 6000) {
+  if (!path) return "";
+  try {
+    const txt = readFileSync(path, "utf8");
+    return txt.slice(Math.max(0, txt.length - maxChars));
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") return "";
+    throw error;
+  }
+}
+
+function detectFailure(logTail) {
+  if (!logTail) return "";
+  const lines = logTail.split("\n");
+  // Bare "out of range" over-matched benign BGM-renderer logs (e.g. a "sample rate
+  // out of range, resampling" notice), mislabelling a healthy track as failed and
+  // silently dropping the music. Anchor to the actual crash strings instead:
+  // Python "(list) index out of range" and torch "index … out of bounds".
+  const idx = lines.findIndex((line) =>
+    /(Traceback|IndexError|RuntimeError|Exception|Killed|No space left|Cannot allocate|index out of range|out of bounds)/i.test(
+      line,
+    ),
+  );
+  if (idx < 0) return "";
+  return lines.slice(idx).join("\n").trim();
+}
+
+function writeStatus(status) {
+  const payload = {
+    generated_at: new Date().toISOString(),
+    ...status,
+  };
+  writeFileSync(outPath, JSON.stringify(payload, null, 2) + "\n");
+  return payload;
+}
+
+if (!existsSync(audioMetaPath)) die(`audio_meta.json missing at ${audioMetaPath}`);
+
+const audioMeta = JSON.parse(readFileSync(audioMetaPath, "utf8"));
+const bgmPath = audioMeta.bgm?.path || "";
+const bgmAbsPath = bgmPath ? join(hyperframesDir, bgmPath) : "";
+const logPath = audioMeta.bgm_log || "";
+const pid = audioMeta.bgm_pid || null;
+
+const base = {
+  enabled: Boolean(audioMeta.bgm_pending && bgmPath),
+  provider: audioMeta.bgm_provider || null,
+  mode: audioMeta.bgm_mode || null,
+  path: bgmPath || null,
+  log: logPath || null,
+  pid,
+  target_duration_s: audioMeta.bgm_target_duration_s || null,
+  seed_duration_s: audioMeta.bgm_seed_duration_s || null,
+  loop_count: audioMeta.bgm_loop_count || null,
+  timeout_ms: timeoutMs,
+};
+
+if (!base.enabled) {
+  const status = writeStatus({
+    ...base,
+    status: "disabled",
+    ready: false,
+    waited_ms: 0,
+    message: "BGM not requested or disabled in audio_meta.json.",
+  });
+  console.log(`✓ bgm: ${status.status} (${status.message})`);
+  process.exit(0);
+}
+
+const started = Date.now();
+let lastFailure = "";
+let lastTail = "";
+
+while (Date.now() - started <= timeoutMs) {
+  if (existsSync(bgmAbsPath)) {
+    const size = statSync(bgmAbsPath).size;
+    writeStatus({
+      ...base,
+      status: "ready",
+      ready: true,
+      waited_ms: Date.now() - started,
+      size_bytes: size,
+      message: `BGM ready at ${bgmPath}.`,
+    });
+    console.log(`✓ bgm: ready (${bgmPath}, ${size}B)`);
+    process.exit(0);
+  }
+
+  lastTail = readTail(logPath);
+  lastFailure = detectFailure(lastTail);
+  const alive = isProcessAlive(pid);
+  if (lastFailure || (!alive && logPath && existsSync(logPath))) {
+    const message = lastFailure
+      ? `BGM renderer failed; see ${logPath}.`
+      : `BGM renderer exited without writing ${bgmPath}; see ${logPath}.`;
+    const status = writeStatus({
+      ...base,
+      status: "failed",
+      ready: false,
+      waited_ms: Date.now() - started,
+      process_alive: alive,
+      message,
+      error_tail: lastFailure || lastTail.slice(-2000),
+    });
+    console.log(`! bgm: failed (${status.message})`);
+    process.exit(0);
+  }
+
+  if (timeoutMs === 0) break;
+  await sleep(Math.min(intervalMs, Math.max(0, timeoutMs - (Date.now() - started))));
+}
+
+const status = writeStatus({
+  ...base,
+  status: "timeout",
+  ready: false,
+  waited_ms: Date.now() - started,
+  process_alive: isProcessAlive(pid),
+  message: `Timed out waiting for ${bgmPath}; assemble-index will skip BGM if still absent.`,
+  log_tail: lastTail.slice(-2000),
+});
+console.log(`! bgm: timeout after ${status.waited_ms}ms (${bgmPath})`);

package/dist/skills/media-use/audio/scripts/wait-bgm.test.mjs

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { runInNewContext } from "node:vm";
+
+const source = readFileSync(new URL("./wait-bgm.mjs", import.meta.url), "utf8");
+const start = source.indexOf("function readTail(");
+const end = source.indexOf("\nfunction detectFailure(", start);
+function load(read) {
+  return runInNewContext(`${source.slice(start, end)}; readTail`, {
+    readFileSync: read,
+    existsSync: () => true,
+    statSync: () => {
+      throw new Error("pathname stat must not precede log read");
+    },
+  });
+}
+
+test("reads a log once without a separate pathname check", () => {
+  let calls = 0;
+  const read = load((path, encoding) => {
+    calls++;
+    assert.equal(path, "renderer.log");
+    assert.equal(encoding, "utf8");
+    return "prefix\nRuntimeError: failed";
+  });
+  assert.equal(read("renderer.log", 20), "RuntimeError: failed");
+  assert.equal(calls, 1);
+});
+
+test("preserves UTF-16 character tail boundaries and zero-length tails", () => {
+  const txt = "🎵日本語".repeat(2000);
+  const read = load(() => txt);
+  assert.equal(read("log"), txt.slice(-6000));
+  assert.equal(read("log", 0), "");
+});
+
+for (const code of ["ENOENT", "ENOTDIR"]) {
+  test(`a log removed during polling is absent (${code})`, () => {
+    const read = load(() => {
+      throw Object.assign(new Error(code), { code });
+    });
+    assert.equal(read("log"), "");
+  });
+}
+
+test("preserves unexpected read errors", () => {
+  const error = Object.assign(new Error("denied"), { code: "EACCES" });
+  assert.throws(
+    () =>
+      load(() => {
+        throw error;
+      })("log"),
+    (caught) => caught === error,
+  );
+});
+
+test("empty log path does not access the filesystem", () => {
+  assert.equal(
+    load(() => {
+      throw new Error("unexpected read");
+    })(""),
+    "",
+  );
+});