dsh-hyperframes 0.10.1 → 0.11.0

package/skills/media-use/scripts/lib/telemetry.test.mjs

@@ -1,73 +1,457 @@
-import assert from "node:assert/strict";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { strict as assert } from "node:assert";
+import { spawn } from "node:child_process";
 import { test } from "node:test";
-import { optedOut } from "./telemetry.mjs";
-
-// optedOut() reads ~/.hyperframes/config.json and env vars. Point HOME at a temp
-// dir so the run never touches the real config, and pin the env opt-outs to a
-// neutral state; restore both afterwards.
-const ENV_KEYS = [
-  "HOME",
-  "USERPROFILE",
-  "HYPERFRAMES_NO_TELEMETRY",
-  "DO_NOT_TRACK",
-  "CI",
-  "NODE_ENV",
-];
-const savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
-const home = mkdtempSync(join(tmpdir(), "mu-telemetry-"));
-const configPath = join(home, ".hyperframes", "config.json");
-
-function writeConfig(contents) {
-  if (contents === null) {
-    rmSync(configPath, { force: true });
-  } else {
-    mkdirSync(dirname(configPath), { recursive: true });
-    writeFileSync(configPath, contents);
-  }
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+  chmodSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { __anonymousIdForTest, __resetTelemetryForTest, optedOut, track } from "./telemetry.mjs";
+
+function sandbox() {
+  const root = mkdtempSync(join(tmpdir(), "mu-telemetry-"));
+  const home = join(root, "home");
+  mkdirSync(home, { recursive: true });
+  process.env.HOME = home;
+  process.env.HYPERFRAMES_MEDIA_HOME = home;
+  return { root, home };
+}
+
+function restoreEnv(saved) {
+  for (const k of Object.keys(process.env)) if (!(k in saved)) delete process.env[k];
+  Object.assign(process.env, saved);
 }
 
-test.before(() => {
-  for (const key of ENV_KEYS) delete process.env[key];
-  process.env.HOME = process.env.USERPROFILE = home;
+function withoutTelemetryOptOut() {
+  for (const k of ["DO_NOT_TRACK", "HYPERFRAMES_NO_TELEMETRY", "CI", "NODE_ENV"])
+    delete process.env[k];
+}
+
+function parseFetchBodies(calls) {
+  return calls.flatMap((call) => JSON.parse(call.options.body).batch);
+}
+
+test("optedOut respects DO_NOT_TRACK / HYPERFRAMES_NO_TELEMETRY / CI", () => {
+  const saved = { ...process.env };
+  try {
+    for (const k of ["DO_NOT_TRACK", "HYPERFRAMES_NO_TELEMETRY", "CI", "NODE_ENV"])
+      delete process.env[k];
+    assert.equal(optedOut(), false, "default: tracking allowed");
+    process.env.DO_NOT_TRACK = "1";
+    assert.equal(optedOut(), true, "DO_NOT_TRACK opts out");
+    delete process.env.DO_NOT_TRACK;
+    process.env.HYPERFRAMES_NO_TELEMETRY = "1";
+    assert.equal(optedOut(), true, "HYPERFRAMES_NO_TELEMETRY opts out");
+    delete process.env.HYPERFRAMES_NO_TELEMETRY;
+    process.env.CI = "true";
+    assert.equal(optedOut(), true, "CI opts out");
+  } finally {
+    for (const k of Object.keys(process.env)) if (!(k in saved)) delete process.env[k];
+    Object.assign(process.env, saved);
+  }
 });
 
-test.after(() => {
-  for (const key of ENV_KEYS) {
-    if (savedEnv[key] === undefined) delete process.env[key];
-    else process.env[key] = savedEnv[key];
+test("optedOut honors telemetryEnabled: false from the shared config", () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  try {
+    withoutTelemetryOptOut();
+    const configPath = join(home, ".hyperframes", "config.json");
+    assert.equal(optedOut(), false, "no config: tracking allowed");
+    mkdirSync(join(home, ".hyperframes"), { recursive: true });
+    writeFileSync(configPath, JSON.stringify({ telemetryEnabled: false }));
+    assert.equal(optedOut(), true, "telemetryEnabled: false opts out");
+    writeFileSync(configPath, JSON.stringify({ telemetryEnabled: true }));
+    assert.equal(optedOut(), false, "telemetryEnabled: true allows tracking");
+    writeFileSync(configPath, "{not json");
+    assert.equal(optedOut(), false, "unreadable config: tracking allowed");
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
   }
-  rmSync(home, { recursive: true, force: true });
 });
 
-test("optedOut is false with no config and no opt-out env", () => {
-  writeConfig(null);
-  assert.equal(optedOut(), false);
+test("track is a no-op (no network, resolves) when opted out", async () => {
+  const savedEnv = { ...process.env };
+  const originalFetch = globalThis.fetch;
+  const { root, home } = sandbox();
+  const calls = [];
+  globalThis.fetch = async (...args) => {
+    calls.push(args);
+    return { ok: true };
+  };
+  process.env.DO_NOT_TRACK = "1";
+  try {
+    // must resolve immediately without throwing or hitting the network
+    await track("media_use_resolve", { type: "bgm", source: "search" });
+    assert.equal(calls.length, 0);
+    assert.equal(existsSync(join(home, ".hyperframes/config.json")), false);
+    assert.equal(existsSync(join(home, ".media/telemetry-notice-shown")), false);
+  } finally {
+    globalThis.fetch = originalFetch;
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+    __resetTelemetryForTest();
+  }
 });
 
-test("optedOut honors telemetryEnabled: false from the shared config", () => {
-  writeConfig(JSON.stringify({ telemetryEnabled: false }));
-  assert.equal(optedOut(), true);
+test("anonymous id uses the shared hyperframes config", () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  try {
+    withoutTelemetryOptOut();
+    mkdirSync(join(home, ".hyperframes"), { recursive: true });
+    writeFileSync(
+      join(home, ".hyperframes/config.json"),
+      JSON.stringify({ anonymousId: "shared-install-id", keep: true }),
+    );
+    mkdirSync(join(home, ".media"), { recursive: true });
+    writeFileSync(join(home, ".media/anon-id"), "old-media-id");
+
+    assert.equal(__anonymousIdForTest(), "shared-install-id");
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+    __resetTelemetryForTest();
+  }
 });
 
-test("optedOut is false when the shared config enables telemetry", () => {
-  writeConfig(JSON.stringify({ telemetryEnabled: true }));
-  assert.equal(optedOut(), false);
+test("anonymous id seeds missing config once and reuses it", () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  try {
+    withoutTelemetryOptOut();
+    const first = __anonymousIdForTest();
+    const configPath = join(home, ".hyperframes/config.json");
+    assert.ok(existsSync(configPath));
+    assert.match(
+      first,
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+    );
+    const second = __anonymousIdForTest();
+    assert.equal(second, first);
+    assert.equal(JSON.parse(readFileSync(configPath, "utf8")).anonymousId, first);
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+    __resetTelemetryForTest();
+  }
 });
 
-test("optedOut treats an unreadable shared config as no opt-out", () => {
-  writeConfig("{not json");
-  assert.equal(optedOut(), false);
+test("anonymous id adopts a legacy ~/.media/anon-id on upgrade (persona continuity)", () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  try {
+    withoutTelemetryOptOut();
+    mkdirSync(join(home, ".media"), { recursive: true });
+    writeFileSync(join(home, ".media/anon-id"), "legacy-media-id");
+    // no ~/.hyperframes/config.json yet — the old media-use-only id must carry over
+    assert.equal(__anonymousIdForTest(), "legacy-media-id");
+    // and it is persisted into the shared config so CLI/studio see the same id
+    assert.equal(
+      JSON.parse(readFileSync(join(home, ".hyperframes/config.json"), "utf8")).anonymousId,
+      "legacy-media-id",
+    );
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+    __resetTelemetryForTest();
+  }
 });
 
-test("optedOut still honors the env opt-outs", () => {
-  writeConfig(JSON.stringify({ telemetryEnabled: true }));
-  process.env.DO_NOT_TRACK = "1";
+test("track identifies a signed-in HeyGen account once and still sends events", async () => {
+  const savedEnv = { ...process.env };
+  const originalFetch = globalThis.fetch;
+  const { root, home } = sandbox();
+  const calls = [];
+  globalThis.fetch = async (url, options) => {
+    calls.push({ url, options });
+    return { ok: true };
+  };
   try {
-    assert.equal(optedOut(), true);
+    withoutTelemetryOptOut();
+    mkdirSync(join(home, ".hyperframes"), { recursive: true });
+    writeFileSync(
+      join(home, ".hyperframes/config.json"),
+      JSON.stringify({ anonymousId: "anon-1" }),
+    );
+    mkdirSync(join(home, ".heygen"), { recursive: true });
+    writeFileSync(
+      join(home, ".heygen/credentials"),
+      JSON.stringify({ user: { email: "alice@example.com", username: "alice" } }),
+    );
+
+    await track("media_use_resolve", { type: "bgm", source: "search" });
+    await track("media_use_resolve", { type: "image", source: "generated" });
+
+    const batch = parseFetchBodies(calls);
+    const identify = batch.filter((item) => item.event === "$identify");
+    assert.equal(identify.length, 1);
+    assert.equal(identify[0].distinct_id, "alice@example.com");
+    assert.equal(identify[0].properties.$anon_distinct_id, "anon-1");
+    assert.equal(batch.filter((item) => item.event === "media_use_resolve").length, 2);
   } finally {
-    delete process.env.DO_NOT_TRACK;
+    globalThis.fetch = originalFetch;
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+    __resetTelemetryForTest();
+  }
+});
+
+test("track identifies with a lowercased email regardless of stored casing", async () => {
+  const savedEnv = { ...process.env };
+  const originalFetch = globalThis.fetch;
+  const { root, home } = sandbox();
+  const calls = [];
+  globalThis.fetch = async (url, options) => {
+    calls.push({ url, options });
+    return { ok: true };
+  };
+  try {
+    withoutTelemetryOptOut();
+    mkdirSync(join(home, ".hyperframes"), { recursive: true });
+    writeFileSync(
+      join(home, ".hyperframes/config.json"),
+      JSON.stringify({ anonymousId: "anon-3" }),
+    );
+    mkdirSync(join(home, ".heygen"), { recursive: true });
+    writeFileSync(
+      join(home, ".heygen/credentials"),
+      JSON.stringify({ user: { email: "Alice@Example.com", username: "alice" } }),
+    );
+
+    await track("media_use_resolve", { type: "bgm", source: "search" });
+
+    const batch = parseFetchBodies(calls);
+    const identify = batch.filter((item) => item.event === "$identify");
+    assert.equal(identify.length, 1);
+    // Lowercased so this joins with heygen-cli's own identify call regardless
+    // of the account's stored email casing -- otherwise the same person could
+    // split into two PostHog profiles by email case alone.
+    assert.equal(identify[0].distinct_id, "alice@example.com");
+  } finally {
+    globalThis.fetch = originalFetch;
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+    __resetTelemetryForTest();
+  }
+});
+
+test("track does not identify when signed out", async () => {
+  const savedEnv = { ...process.env };
+  const originalFetch = globalThis.fetch;
+  const { root, home } = sandbox();
+  const calls = [];
+  globalThis.fetch = async (url, options) => {
+    calls.push({ url, options });
+    return { ok: true };
+  };
+  try {
+    withoutTelemetryOptOut();
+    mkdirSync(join(home, ".hyperframes"), { recursive: true });
+    writeFileSync(
+      join(home, ".hyperframes/config.json"),
+      JSON.stringify({ anonymousId: "anon-2" }),
+    );
+
+    await track("media_use_resolve", { type: "bgm", source: "search" });
+
+    const batch = parseFetchBodies(calls);
+    assert.equal(
+      batch.some((item) => item.event === "$identify"),
+      false,
+    );
+    assert.equal(batch[0].event, "media_use_resolve");
+    assert.equal(batch[0].distinct_id, "anon-2");
+  } finally {
+    globalThis.fetch = originalFetch;
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+    __resetTelemetryForTest();
+  }
+});
+
+test("first run notice prints to stderr once and never stdout", async () => {
+  const savedEnv = { ...process.env };
+  const originalFetch = globalThis.fetch;
+  const originalError = console.error;
+  const originalLog = console.log;
+  const { root, home } = sandbox();
+  const stderr = [];
+  const stdout = [];
+  globalThis.fetch = async () => ({ ok: true });
+  console.error = (...args) => stderr.push(args.join(" "));
+  console.log = (...args) => stdout.push(args.join(" "));
+  try {
+    withoutTelemetryOptOut();
+    await track("media_use_resolve", { type: "bgm" });
+    await track("media_use_resolve", { type: "sfx" });
+
+    assert.equal(stderr.length, 1);
+    assert.match(stderr[0], /media-use sends usage telemetry/);
+    assert.equal(stdout.length, 0);
+    // notice-shown lives in the shared config (config.telemetryNoticeShown), so
+    // the CLI and media-use show it once per person — not a media-use-only marker.
+    assert.equal(
+      JSON.parse(readFileSync(join(home, ".hyperframes/config.json"), "utf8")).telemetryNoticeShown,
+      true,
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+    console.error = originalError;
+    console.log = originalLog;
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+    __resetTelemetryForTest();
+  }
+});
+
+test("warns once on stderr when MEDIA_USE_TELEMETRY_HOST is set outside a test/CI context", async () => {
+  const savedEnv = { ...process.env };
+  const originalFetch = globalThis.fetch;
+  const originalError = console.error;
+  const { root } = sandbox();
+  const stderr = [];
+  globalThis.fetch = async () => ({ ok: true });
+  console.error = (...args) => stderr.push(args.join(" "));
+  try {
+    // No opt-out, no CI/NODE_ENV signal — mirrors a real user's shell where
+    // this test-only var leaked in by accident and tracking is not disabled.
+    withoutTelemetryOptOut();
+    process.env.MEDIA_USE_TELEMETRY_HOST = "http://127.0.0.1:1"; // nothing listens; irrelevant here
+    await track("media_use_resolve", { type: "bgm" });
+    await track("media_use_resolve", { type: "bgm" });
+
+    const warnings = stderr.filter((line) => line.includes("MEDIA_USE_TELEMETRY_HOST"));
+    assert.equal(warnings.length, 1, "expected exactly one warning across repeated calls");
+  } finally {
+    globalThis.fetch = originalFetch;
+    console.error = originalError;
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+    __resetTelemetryForTest();
+  }
+});
+
+test("does not warn when MEDIA_USE_TELEMETRY_HOST is set the way the U7 interception test sets it", async () => {
+  const savedEnv = { ...process.env };
+  const originalFetch = globalThis.fetch;
+  const originalError = console.error;
+  const { root } = sandbox();
+  const stderr = [];
+  globalThis.fetch = async () => ({ ok: true });
+  console.error = (...args) => stderr.push(args.join(" "));
+  try {
+    withoutTelemetryOptOut();
+    // Same env shape resolve.test.mjs's U7 test uses to allow tracking through:
+    // DO_NOT_TRACK=0, CI unset/empty, NODE_ENV=test.
+    process.env.DO_NOT_TRACK = "0";
+    process.env.CI = "";
+    process.env.NODE_ENV = "test";
+    process.env.MEDIA_USE_TELEMETRY_HOST = "http://127.0.0.1:1";
+    await track("media_use_resolve", { type: "bgm" });
+
+    assert.equal(
+      stderr.some((line) => line.includes("MEDIA_USE_TELEMETRY_HOST")),
+      false,
+      "the U7 test's own use of the override must not print a spurious warning",
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+    console.error = originalError;
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+    __resetTelemetryForTest();
+  }
+});
+
+test("read-only telemetry state degrades without throwing", async () => {
+  const savedEnv = { ...process.env };
+  const originalFetch = globalThis.fetch;
+  const { root, home } = sandbox();
+  globalThis.fetch = async () => ({ ok: true });
+  try {
+    withoutTelemetryOptOut();
+    writeFileSync(join(home, ".hyperframes"), "not a directory");
+    writeFileSync(join(home, ".media"), "not a directory");
+    await track("media_use_resolve", { type: "bgm" });
+  } finally {
+    globalThis.fetch = originalFetch;
+    try {
+      chmodSync(join(home, ".hyperframes"), 0o600);
+    } catch {
+      // best effort for cleanup on platforms with different chmod behavior
+    }
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+    __resetTelemetryForTest();
+  }
+});
+
+async function trackQuietly(home) {
+  const originalFetch = globalThis.fetch;
+  const originalError = console.error;
+  globalThis.fetch = async () => ({ ok: true });
+  console.error = () => {};
+  try {
+    withoutTelemetryOptOut();
+    await track("media_use_resolve", { type: "bgm" });
+    return readFileSync(join(home, ".hyperframes/config.json"), "utf8");
+  } finally {
+    globalThis.fetch = originalFetch;
+    console.error = originalError;
+  }
+}
+
+test("waits for another process's locked settings write, then keeps the no it saved", async () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  const dir = join(home, ".hyperframes");
+  mkdirSync(dir, { recursive: true });
+  const holder = spawn(process.execPath, [
+    "-e",
+    `const fs = require("fs");
+      const dir = process.argv[1];
+      fs.writeFileSync(dir + "/config.json.lock", "", { flag: "wx" });
+      process.stdout.write("locked\\n");
+      setTimeout(() => {
+        fs.writeFileSync(dir + "/other.tmp", JSON.stringify({ localEmbeddingEnabled: false }));
+        fs.renameSync(dir + "/other.tmp", dir + "/config.json");
+        fs.rmSync(dir + "/config.json.lock");
+      }, 1000);`,
+    dir,
+  ]);
+  const exited = new Promise((done) => holder.on("exit", done));
+  try {
+    await new Promise((locked) => holder.stdout.once("data", locked));
+    const saved = JSON.parse(await trackQuietly(home));
+    await exited;
+    assert.equal(saved.localEmbeddingEnabled, false);
+    assert.equal(saved.telemetryNoticeShown, true);
+    assert.equal(typeof saved.anonymousId, "string");
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+    __resetTelemetryForTest();
+  }
+});
+
+test("leaves a settings file it cannot read untouched", async () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  mkdirSync(join(home, ".hyperframes"), { recursive: true });
+  writeFileSync(join(home, ".hyperframes/config.json"), "{not json");
+  try {
+    assert.equal(await trackQuietly(home), "{not json");
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+    __resetTelemetryForTest();
   }
 });

package/skills/media-use/scripts/lib/test-home.test.mjs

@@ -0,0 +1,10 @@
+import assert from "node:assert/strict";
+import { realpathSync } from "node:fs";
+import { homedir, tmpdir, userInfo } from "node:os";
+import { sep } from "node:path";
+import { test } from "node:test";
+
+test("the skills test run has a home folder of its own, not the user's", () => {
+  assert.ok(realpathSync(homedir()).startsWith(realpathSync(tmpdir()) + sep));
+  assert.notEqual(homedir(), userInfo().homedir);
+});

package/skills/media-use/scripts/lib/transcriptCutFade.test.mjs

@@ -0,0 +1,33 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { fadeFilterFor } from "./transcriptCutFade.mjs";
+
+test("fades in only at the first segment's trailing splice", () => {
+  assert.equal(fadeFilterFor(2, { fadeIn: false, fadeOut: true }), "afade=t=out:st=1.97:d=0.03");
+});
+
+test("fades both edges of a middle segment's two splices", () => {
+  assert.equal(
+    fadeFilterFor(2, { fadeIn: true, fadeOut: true }),
+    "afade=t=in:st=0:d=0.03,afade=t=out:st=1.97:d=0.03",
+  );
+});
+
+test("fades out only at the last segment's leading splice", () => {
+  assert.equal(fadeFilterFor(2, { fadeIn: true, fadeOut: false }), "afade=t=in:st=0:d=0.03");
+});
+
+test("a single kept segment borders no splice at all", () => {
+  assert.equal(fadeFilterFor(2, { fadeIn: false, fadeOut: false }), null);
+});
+
+test("still scales the ramp down on a short segment with both edges faded", () => {
+  assert.equal(
+    fadeFilterFor(0.08, { fadeIn: true, fadeOut: true }),
+    "afade=t=in:st=0:d=0.02,afade=t=out:st=0.06:d=0.02",
+  );
+});
+
+test("skips a degenerate segment even when a splice is requested", () => {
+  assert.equal(fadeFilterFor(0.005, { fadeIn: true, fadeOut: true }), null);
+});

package/skills/media-use/scripts/lib/tts-local-provider.mjs

@@ -0,0 +1,94 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ffprobeBinary } from "./ff-binaries.mjs";
+import { resolveSpawnCommand } from "../../audio/scripts/lib/tts.mjs";
+
+// Local voiceover via the packaged Kokoro-82M TTS (the `hyperframes tts` CLI),
+// the free/private default now that HeyGen TTS costs wallet credits. Kokoro runs
+// on-device (CPU, faster-than-realtime, bundled voices, native word timestamps),
+// so no key and no per-call charge. When Kokoro is not set up, this returns null
+// and the registry falls through to the HeyGen TTS upsell.
+//
+// Delegated to the hyperframes CLI (same as transcribe / remove-background), not
+// re-implemented here. ffprobe reads the duration back for the ledger.
+
+function probeDurationSeconds(ffprobe, file) {
+  try {
+    const out = execFileSync(
+      ffprobe,
+      ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", "--", file],
+      { encoding: "utf8", timeout: 15000 },
+    );
+    const d = parseFloat(String(out).trim());
+    return Number.isFinite(d) ? d : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// `platform`/`execFn`/`env`/`pathExists` params (defaulting to the real
+// values) exist so tests can exercise the win32 branch without mocking
+// node:child_process (its ESM exports are non-configurable) — same idiom as
+// spawnP in ../../audio/scripts/lib/tts.mjs.
+export async function localTtsGenerate(
+  intent,
+  ctx,
+  platform = process.platform,
+  execFn = execFileSync,
+  env = process.env,
+  pathExists = existsSync,
+) {
+  const ffprobe = ffprobeBinary();
+  const outPath = join(tmpdir(), `media-use-kokoro-${process.pid}-${Date.now()}.wav`);
+  const argv = ["hyperframes", "tts", intent, "--output", outPath];
+  if (ctx?.voice) argv.push("--voice", ctx.voice);
+  if (ctx?.lang && ctx.lang !== "en") argv.push("--lang", ctx.lang);
+  // On Windows a bare "npx" is npx.cmd, which execFileSync cannot exec
+  // (spawnSync npx ENOENT) — resolveSpawnCommand reroutes it through
+  // node + npx-cli.js, same as the audio engine's TTS spawns.
+  const resolved = resolveSpawnCommand(
+    "npx",
+    argv,
+    { encoding: "utf8", timeout: 300000, stdio: ["ignore", "pipe", "pipe"] },
+    platform,
+    env,
+    pathExists,
+  );
+  if (!resolved) {
+    // npx-on-win32 with no resolvable npx-cli.js — same terminal condition
+    // spawnP warns about. Fall through to the next provider rather than crash.
+    console.error(
+      "media-use: local voice not enabled (kokoro). Cannot run npx on Windows: " +
+        "npm's npx-cli.js was not found (install npm with Node, or run via npx/npm run so npm_execpath is set).",
+    );
+    return null;
+  }
+  try {
+    execFn(resolved.cmd, resolved.args, resolved.opts);
+  } catch (err) {
+    // `hyperframes tts` prints its "kokoro-onnx not installed" hint to stdout
+    // (clack UI), so read both streams and surface the actionable enable-command
+    // rather than a bare "Command failed": otherwise resolve silently falls
+    // through to the PAID HeyGen TTS upsell when free local voice was one pip away.
+    const out = `${err.stdout?.toString() ?? ""}${err.stderr?.toString() ?? ""}`.trim();
+    const hint = /not installed|pip install kokoro/i.test(out)
+      ? "install for free on-device voice: pip install kokoro-onnx soundfile (or set HYPERFRAMES_PYTHON to a venv that has it)"
+      : out.slice(-200) || err.message;
+    console.error(`media-use: local voice not enabled (kokoro). ${hint}`);
+    return null;
+  }
+  if (!existsSync(outPath) || statSync(outPath).size === 0) return null;
+  return {
+    localPath: outPath,
+    ext: ".wav",
+    source: "generated",
+    metadata: {
+      description: intent,
+      provider: "kokoro.local",
+      duration: probeDurationSeconds(ffprobe, outPath),
+      provenance: { engine: "kokoro-82m", prompt: intent },
+    },
+  };
+}