hyperframes 0.8.150 → 0.8.151

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

@@ -0,0 +1,175 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const ttsUrl = new URL("./tts.mjs", import.meta.url).href;
+const stub = `#!${process.execPath}
+const fs = require("node:fs");
+const path = require("node:path");
+const args = process.argv.slice(2);
+if (args[0] === "--version") {
+  console.log("Python 3.12.0");
+  process.exit(0);
+}
+const input = args[2];
+const output = args[0] === "-c" ? args[4] : args[args.indexOf("--output") + 1];
+const text = fs.readFileSync(input, "utf8");
+fs.writeFileSync(output + ".started", input);
+const finish = () => {
+  if (text === "slow" && !fs.existsSync(process.env.RELEASE_FILE)) {
+    setTimeout(finish, 5);
+    return;
+  }
+  const consumed = fs.readFileSync(input, "utf8");
+  fs.writeFileSync(output + ".json", JSON.stringify({ input, text, consumed, args }));
+  if (process.env.CASE_MODE === "nonzero") process.exit(7);
+  if (process.env.CASE_MODE !== "no-output") fs.writeFileSync(output, consumed);
+};
+setTimeout(finish, 10);
+`;
+
+const exercise = `
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import childProcess from "node:child_process";
+import { syncBuiltinESMExports } from "node:module";
+import { join, dirname } from "node:path";
+const { CASE_ROOT: root, CASE_MODE: mode, CASE_PROVIDER: provider } = process.env;
+const temp = join(root, "tmp");
+const preexisting = join(temp, "hf-txt-preexisting");
+fs.mkdirSync(preexisting);
+fs.writeFileSync(join(preexisting, "marker"), "keep");
+const injected = Object.assign(new Error("synthetic " + mode), { code: "EACCES" });
+const originalMkdtemp = fs.mkdtempSync;
+const originalWrite = fs.writeFileSync;
+const originalRm = fs.rmSync;
+if (mode === "allocation") fs.mkdtempSync = (prefix, ...args) => {
+  if (prefix.startsWith(join(temp, "hf-txt-"))) throw injected;
+  return originalMkdtemp(prefix, ...args);
+};
+if (mode === "write") fs.writeFileSync = (file, ...args) => {
+  if (String(file).endsWith("line.txt")) {
+    originalWrite(file, "partial");
+    throw injected;
+  }
+  return originalWrite(file, ...args);
+};
+if (mode === "spawn-throw") childProcess.spawn = () => { throw injected; };
+if (mode === "cleanup") fs.rmSync = (dir, ...args) => {
+  if (String(dir).startsWith(join(temp, "hf-txt-"))) throw injected;
+  return originalRm(dir, ...args);
+};
+syncBuiltinESMExports();
+const { synthesizeOne } = await import(${JSON.stringify(ttsUrl)});
+const project = join(root, "project");
+const wavAbs = join(project, "line.wav");
+const request = (chosen = provider, text = "synthetic café", output = wavAbs) =>
+  synthesizeOne({ provider: chosen, text, voiceId: "synthetic-voice", lang: "es",
+    speed: 0.8, wavAbs: output, hyperframesDir: project });
+const owned = () => fs.readdirSync(temp).filter(name => name !== "hf-txt-preexisting");
+if (["allocation", "write", "spawn-throw"].includes(mode)) {
+  await assert.rejects(request(), error => error === injected);
+  assert.equal(fs.existsSync(wavAbs), false);
+} else if (mode === "concurrent") {
+  const slowWav = join(project, "slow.wav");
+  const slow = request("elevenlabs", "slow", slowWav);
+  try {
+    const deadline = Date.now() + 5000;
+    while (!fs.existsSync(slowWav + ".started")) {
+      assert.ok(Date.now() < deadline, "slow subprocess must start");
+      await new Promise(resolve => setTimeout(resolve, 5));
+    }
+    const slowInput = fs.readFileSync(slowWav + ".started", "utf8");
+    assert.deepEqual(await request("kokoro"), { ok: true, words: null });
+    assert.deepEqual(owned(), [dirname(slowInput).split(/[\\\\/]/).pop()]);
+    assert.equal(fs.readFileSync(slowInput, "utf8"), "slow");
+  } finally {
+    fs.writeFileSync(process.env.RELEASE_FILE, "release");
+    await slow;
+  }
+  assert.equal(fs.readFileSync(slowWav, "utf8"), "slow");
+} else {
+  const result = await request();
+  const label = provider === "elevenlabs" ? "elevenlabs (python)" : "kokoro (npx hyperframes tts)";
+  if (["nonzero", "enoent", "no-output"].includes(mode)) {
+    const error = mode === "no-output" ? label + " produced no wav file" :
+      label + " exited with status " + (mode === "enoent" ? -1 : 7);
+    assert.deepEqual(result, { ok: false, words: null, error });
+    assert.equal(fs.existsSync(wavAbs), false);
+  } else {
+    assert.deepEqual(result, { ok: true, words: null });
+    assert.equal(fs.readFileSync(wavAbs, "utf8"), "synthetic café");
+  }
+  if (mode !== "enoent") {
+    const log = JSON.parse(fs.readFileSync(wavAbs + ".json", "utf8"));
+    assert.equal(log.text, "synthetic café");
+    assert.equal(log.consumed, log.text);
+    if (provider === "kokoro") assert.deepEqual(log.args.slice(-4), ["--lang", "es", "--speed", "0.8"]);
+  }
+}
+if (mode === "cleanup") assert.equal(owned().length, 1);
+else assert.deepEqual(owned(), [], "owned text directories must be removed");
+assert.equal(fs.readFileSync(join(preexisting, "marker"), "utf8"), "keep");
+`;
+
+function runCase(provider, mode) {
+  const root = mkdtempSync(join(tmpdir(), "tts-cleanup-test-"));
+  try {
+    for (const dir of ["home", "tmp", "bin", "project"]) mkdirSync(join(root, dir));
+    if (mode !== "enoent") {
+      for (const name of ["npx", "python3"]) {
+        const executable = join(root, "bin", name);
+        writeFileSync(executable, stub);
+        chmodSync(executable, 0o755);
+      }
+    }
+    const result = spawnSync(process.execPath, ["--input-type=module", "-e", exercise], {
+      encoding: "utf8",
+      timeout: 15000,
+      env: {
+        HOME: join(root, "home"),
+        USERPROFILE: join(root, "home"),
+        TMPDIR: join(root, "tmp"),
+        TMP: join(root, "tmp"),
+        TEMP: join(root, "tmp"),
+        PATH: join(root, "bin"),
+        CASE_ROOT: root,
+        CASE_PROVIDER: provider,
+        CASE_MODE: mode,
+        RELEASE_FILE: join(root, "release"),
+      },
+    });
+    assert.equal(result.error, undefined);
+    assert.equal(result.status, 0, result.stdout + result.stderr);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+for (const provider of ["elevenlabs", "kokoro"]) {
+  for (const mode of [
+    "success",
+    "nonzero",
+    "no-output",
+    "enoent",
+    "spawn-throw",
+    "allocation",
+    "write",
+    "cleanup",
+  ]) {
+    test(
+      `synthesizeOne(${provider}) preserves ${mode} behavior and cleans only its text directory`,
+      { skip: process.platform === "win32" },
+      () => runCase(provider, mode),
+    );
+  }
+}
+
+test(
+  "concurrent providers retain each other's text until their subprocess finishes",
+  { skip: process.platform === "win32" },
+  () => runCase("kokoro", "concurrent"),
+);

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

@@ -234,7 +234,7 @@ import os, sys
 from elevenlabs.client import ElevenLabs
 from elevenlabs import save
 client = ElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"])
-text = open(sys.argv[1]).read()
+text = open(sys.argv[1], encoding="utf-8").read()
 audio = client.text_to_speech.convert(
     text=text, voice_id=sys.argv[2],
     model_id="eleven_multilingual_v2", output_format="mp3_44100_128",
@@ -274,23 +274,21 @@ export async function synthesizeOne({
     } catch {
       return { ok: false, words: null };
     }
-    const { cmd, args } = pythonInvocation([
-      "-c",
-      ELEVENLABS_PY,
-      writeTmpText(text),
-      voiceId,
-      wavAbs,
-    ]);
-    const r = await spawnP(cmd, args, {});
-    return synthResult(r, wavAbs, "elevenlabs (python)");
+    return withTmpText(text, async (textPath) => {
+      const { cmd, args } = pythonInvocation(["-c", ELEVENLABS_PY, textPath, voiceId, wavAbs]);
+      const r = await spawnP(cmd, args, {});
+      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);
-  if (speed !== 1) args.push("--speed", String(speed));
-  const r = await spawnP("npx", args, { cwd: hyperframesDir });
-  return synthResult(r, wavAbs, "kokoro (npx hyperframes tts)");
+  return withTmpText(text, async (textPath) => {
+    const args = ["hyperframes", "tts", textPath, "--voice", voiceId, "--output", wavRel];
+    if (lang !== "en") args.push("--lang", lang);
+    if (speed !== 1) args.push("--speed", String(speed));
+    const r = await spawnP("npx", args, { cwd: hyperframesDir });
+    return synthResult(r, wavAbs, "kokoro (npx hyperframes tts)");
+  });
 }
 
 // Shape a spawn result into { ok, words, error }, naming why on failure so the
@@ -378,11 +376,18 @@ export async function transcribeWav({ wavRel, lang = "en", hyperframesDir }) {
 }
 
 // ── tiny local utils ──────────────────────────────────────────────────────────
-function writeTmpText(text) {
+async function withTmpText(text, run) {
   const td = mkdtempSync(join(tmpdir(), "hf-txt-"));
-  const p = join(td, "line.txt");
-  writeFileSync(p, text);
-  return p;
+  try {
+    const p = join(td, "line.txt");
+    writeFileSync(p, text);
+    return await run(p);
+  } finally {
+    // Cleanup must preserve the synthesis result or the original write/spawn error.
+    try {
+      rmSync(td, { recursive: true, force: true });
+    } catch {}
+  }
 }
 function relTo(base, abs) {
   return abs.startsWith(base + "/") ? abs.slice(base.length + 1) : abs;

package/dist/skills/media-use/references/grading.md

@@ -17,7 +17,7 @@ Stop here and use that treatment workflow for requests such as retro, old home
 video, camcorder, film, print, ASCII, glitch, privacy, or a media reveal. Do not
 assemble those from a generic LUT plus handmade CSS vignette/grain/opacity.
 
-**Never `cat`/read a `.cube` file into context.** A 3D LUT is ~size^3 lines of raw numbers (33^3 ≈ 36k lines at the default size). It bloats context and carries zero human/agent-legible signal. To understand or choose a LUT, use `hyperframes grade-compare` to see it rendered, or `cube-validate.mjs` for a one-line `{ok,size}` check. Read `.media/index.md` or `luts/index.json` for the description. Never read the LUT body itself.
+**Never `cat`/read a `.cube` file into context.** A 3D LUT is ~size^3 lines of raw numbers (33^3 ≈ 36k lines at the default size). It bloats context and carries zero human/agent-legible signal. To understand or choose a LUT, use `hyperframes grade-compare` to see it rendered. `npx hyperframes media-use resolve --type lut --intent "<look description>" --project .` validates generated or downloaded LUTs before freezing them; the validator is bundled in the CLI, not shipped as a standalone skill script. Read `<project>/.media/index.md` or `luts/index.json` for the description. Never read the LUT body itself.
 
 ```bash
 npx hyperframes media-use resolve --type grade --intent "warm daylight" --project . --json
@@ -158,5 +158,4 @@ validates generated or downloaded cubes as it freezes them under
 
 ```bash
 npx hyperframes media-use resolve --type lut --intent "teal orange blockbuster" --project . --json
-node skills/media-use/scripts/lib/cube-validate.mjs .media/luts/lut_001.cube
 ```

package/dist/skills/media-use/references/meta.md

@@ -4,22 +4,22 @@ Maintainer-facing reference. Nothing here changes how you resolve or operate on
 
 ## What it owns (the gaps HyperFrames leaves)
 
-HyperFrames owns media _playback_; media-use owns everything else. Each row is enforced by `scripts/lib/coverage.test.mjs` so the claim can't rot.
-
-| HyperFrames gap                            | media-use owns it via                                                                                                                                                                                                                                                               |
-| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Audio-only, no image/icon                  | `resolve --type image\|icon` (heygen asset search)                                                                                                                                                                                                                                  |
-| No third-party brand logos                 | `resolve --type logo` (theSVG → GitHub org avatar → domain favicon)                                                                                                                                                                                                                 |
-| No voice / audio generation                | `resolve --type voice` (HeyGen TTS free-usage path; optional local Kokoro) + the audio engine (`audio/scripts/audio.mjs`)                                                                                                                                                           |
-| Scattered/duplicated audio engine          | one consolidated engine under `audio/` (hyperframes-media retired)                                                                                                                                                                                                                  |
-| No agent media-ops (cut/reframe/transform) | `references/operations.md` + `resolve --from` to register outputs                                                                                                                                                                                                                   |
-| No transcript-driven cutting               | `scripts/transcript-cut.mjs` compiles word-timestamp edits into cut lists                                                                                                                                                                                                           |
-| No auto-duck / publish loudness            | `scripts/audio-duck.mjs` + `references/operations.md` loudnorm/sidechain recipes                                                                                                                                                                                                    |
-| No cross-project memory                    | global content-addressed cache + auto-promote (`~/.media`)                                                                                                                                                                                                                          |
-| Grade recipes and LUT freezing             | `resolve --type grade` emits a paste-ready recipe and `resolve --type lut` freezes validated `.cube` files; direct element analysis/authoring lives in `hyperframes media-treatment`                                                                                                |
-| No image generation                        | RAM-graded local mflux (FLUX) via `scripts/lib/mflux-provider.mjs`, codex `image_gen` upsell (`scripts/lib/codex-provider.mjs`)                                                                                                                                                     |
-| No video generation                        | `resolve --type video` — HeyGen avatar video first (free-usage path, sign-in nudge on auth failure), local LTX fallback (`videogen` in `scripts/lib/local-models.mjs`); image-to-video, photo-avatar, dub/translate remain manual `heygen` CLI recipes (`references/operations.md`) |
-| Weak local-model defaults                  | HeyGen free-usage path via the `heygen` CLI; local open-source tools only as opt-in alternatives (`scripts/lib/local-run.mjs`)                                                                                                                                                      |
+HyperFrames owns media _playback_; media-use owns everything else. Each row is enforced by `packages/cli/src/media-use/lib/coverage.test.mjs` so the claim can't rot.
+
+| HyperFrames gap                            | media-use owns it via                                                                                                                                                                                                                                    |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Audio-only, no image/icon                  | `resolve --type image\|icon` (heygen asset search)                                                                                                                                                                                                       |
+| No third-party brand logos                 | `resolve --type logo` (theSVG → GitHub org avatar → domain favicon)                                                                                                                                                                                      |
+| No voice / audio generation                | `resolve --type voice` (HeyGen TTS free-usage path; optional local Kokoro) + the audio engine (`audio/scripts/audio.mjs`)                                                                                                                                |
+| Scattered/duplicated audio engine          | one consolidated engine under `audio/` (hyperframes-media retired)                                                                                                                                                                                       |
+| No agent media-ops (cut/reframe/transform) | `references/operations.md` + `resolve --from` to register outputs                                                                                                                                                                                        |
+| No transcript-driven cutting               | `scripts/transcript-cut.mjs` compiles word-timestamp edits into cut lists                                                                                                                                                                                |
+| No auto-duck / publish loudness            | `scripts/audio-duck.mjs` + `references/operations.md` loudnorm/sidechain recipes                                                                                                                                                                         |
+| No cross-project memory                    | global content-addressed cache + auto-promote (`~/.media`)                                                                                                                                                                                               |
+| Grade recipes and LUT freezing             | `resolve --type grade` emits a paste-ready recipe and `resolve --type lut` freezes validated `.cube` files; direct element analysis/authoring lives in `hyperframes media-treatment`                                                                     |
+| No image generation                        | `resolve --type image` — RAM-graded local mflux (FLUX), codex `image_gen` upsell                                                                                                                                                                         |
+| No video generation                        | `resolve --type video` — HeyGen avatar video first (free-usage path, sign-in nudge on auth failure), local LTX fallback (`videogen` ladder); image-to-video, photo-avatar, dub/translate remain manual `heygen` CLI recipes (`references/operations.md`) |
+| Weak local-model defaults                  | HeyGen free-usage path via the `heygen` CLI; local open-source tools only as opt-in alternatives                                                                                                                                                         |
 
 ## Usage stats
 
@@ -47,7 +47,7 @@ dev). Same public PostHog project key and opt-outs as the `hyperframes` CLI.
 
 HeyGen request tagging: every generating `heygen` call (TTS, avatar video, catalog
 search) carries the allowlisted `X-HeyGen-Client-Source: media-use` header, sourced
-from one shared constant (`HEYGEN_CLIENT_SOURCE_ARGV` in `scripts/lib/heygen-cli.mjs`)
+from one shared constant (`HEYGEN_CLIENT_SOURCE_ARGV` in `packages/cli/src/media-use/lib/heygen-cli.mjs`)
 so a future call site can't silently ship untagged. Read-only discovery calls
 (`voice list`, `avatar list`) are intentionally left untagged.
 

package/dist/skills/media-use/references/operations.md

@@ -210,9 +210,9 @@ ffmpeg -i mix.wav \
 GENERATES. Two paths, best-for-the-machine picked automatically:
 
 1. **Local (default, free, private): mflux** (FLUX-on-MLX). `resolve` spec-checks
-   AVAILABLE RAM and runs the best FLUX-class model that fits, via
-   `scripts/lib/local-models.mjs` (`imagegen` ladder) + `mflux-provider.mjs`.
-   The RAM ladder (agent sees it via `describeModelLadder("imagegen", specs)`):
+   AVAILABLE RAM and runs the best FLUX-class model that fits, using the
+   CLI-bundled `imagegen` ladder (its modules are not shipped in the standalone
+   skill). The RAM ladder:
 
    | Tier   | Model                | Needs (available RAM) | Notes                               |
    | ------ | -------------------- | --------------------- | ----------------------------------- |
@@ -245,7 +245,7 @@ clip), so treat the fallback as "HeyGen wasn't reachable," not "upgrade the
 quality":
 
 - **HeyGen avatar video (default, free for new API users):**
-  `heygenVideoGenerate` (`scripts/lib/heygen-video-provider.mjs`) shells the
+  The CLI-bundled provider shells the
   `heygen` CLI — never the raw API — auto-picking a public avatar and a
   starfish voice (override with `--avatar-id`/`--voice-id`, threaded through
   as `ctx.avatarId`/`ctx.voiceId`). If the CLI reports `not_authenticated`,
@@ -253,13 +253,13 @@ quality":
   new API users — sign in) to stderr and falls through to LTX instead of
   hard-failing.
 - **Local fallback: LTX 2.3 on MLX** via `dgrauet/ltx-2-mlx`, the `videogen`
-  ladder in `local-models.mjs` (`ltx-video-provider.mjs`). Generative clips
+  ladder bundled in the HyperFrames CLI. Generative clips
   (t2v), spec-gated to RAM. Verified on 24GB: 512x320 x 33f with audio.
 
 Every generating `heygen` call from media-use — TTS, avatar video, and
 catalog search — sends the allowlisted `X-HeyGen-Client-Source: media-use`
 header (persistent flag, works on every subcommand) via the shared
-`HEYGEN_CLIENT_SOURCE_ARGV` constant (`scripts/lib/heygen-cli.mjs`), so usage
+CLI-internal `HEYGEN_CLIENT_SOURCE_ARGV` constant, so usage
 tags correctly in billing/resource meta and shows up in the API dashboards.
 Read-only discovery (`avatar list`, `voice list`) doesn't need it.
 

package/dist/skills/media-use/references/setup-providers.md

@@ -36,8 +36,8 @@ before resolving bgm/sfx/image/icon/voice/avatar-video; music and sound effects
 a host app's own tools need none of it. Local tools are opt-in
 alternatives where they exist: mflux for image, Kokoro for voice, Parakeet for
 transcription, and LTX for local video generation. `resolve` spec-checks
-AVAILABLE RAM for those local ladders (`describeModelLadder`); the agent can
-see the ladder and override.
+AVAILABLE RAM for those local ladders inside the CLI (the image tiers are listed
+in `references/operations.md`).
 
 | Type      | Provider / path                                                                                                                                                               |
 | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -84,8 +84,7 @@ private, on-device path instead of or ahead of HeyGen for that type. Only
 | `npx hyperframes`  | Kokoro TTS (voice), Parakeet or whisper.cpp (transcribe), remove-background     | via the hyperframes CLI; Parakeet on macOS, Windows and glibc 2.32+ Linux: `npx hyperframes models install parakeet`; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake) |
 
 The RAM-graded local-model shortlist + exact per-tier install/invoke lives in
-`scripts/lib/local-models.mjs` (the agent can read `describeModelLadder(cap, specs)`
-to see which model fits this machine). Without a tool on PATH, its provider
+the CLI's bundled media-use engine, not in the standalone skill. Without a tool on PATH, its provider
 prints a one-line diagnostic to stderr and resolve falls through where another
 provider exists (e.g. no `mflux` -> codex image upsell; no `parakeet-mlx` -> whisper.cpp).
 

package/dist/skills/media-use/scripts/lib/cutlist.mjs

@@ -148,7 +148,7 @@ function clampRanges(ranges, duration) {
 
 function mergeRanges(ranges) {
   const sorted = ranges
-    .map((range) => ({ start: round3(range.start), end: round3(range.end) }))
+    .map((range) => ({ start: round6(range.start), end: round6(range.end) }))
     .sort((a, b) => a.start - b.start || a.end - b.end);
   const merged = [];
   for (const range of sorted) {
@@ -173,12 +173,19 @@ function invertRanges(removals, duration) {
   return kept;
 }
 
+// Range bounds are rounded only to shed float noise, never to the millisecond:
+// these values become ffmpeg's -ss/-to, where a millisecond is wide enough to
+// step a boundary onto the next frame at 29.97/30/60 fps.
 function finalizeKept(ranges) {
   return mergeRanges(ranges)
-    .map((range) => ({ start: round3(range.start), end: round3(range.end) }))
+    .map((range) => ({ start: round6(range.start), end: round6(range.end) }))
     .filter((range) => round3(range.end - range.start) >= MIN_SEGMENT_SECONDS);
 }
 
+function round6(n) {
+  return Math.round(Number(n) * 1e6) / 1e6;
+}
+
 function round3(n) {
   return Math.round(Number(n) * 1000) / 1000;
 }

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

@@ -113,6 +113,18 @@ test("--keep is inverse mode and coalesces direct kept ranges", () => {
   ]);
 });
 
+test("kept ranges keep frame precision instead of rounding to the millisecond", () => {
+  const transcript = [word("w0", "start", 0, 1), word("w1", "end", 14, 15)];
+
+  // Frame 386 at 30 fps is 12.866666 s. These bounds become ffmpeg's -ss/-to, so
+  // rounding them to 12.867 hands ffmpeg a time just past the frame and the
+  // segment starts one frame late.
+  assert.deepEqual(compileCutList(transcript, { keep: "0-1,12.866666666666667-14" }), [
+    { start: 0, end: 1 },
+    { start: 12.866667, end: 14 },
+  ]);
+});
+
 test("--plan on a fixture transcript prints the exact segment JSON", () => {
   const dir = mkdtempSync(join(tmpdir(), "media-use-cutlist-"));
   try {

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

@@ -35,9 +35,12 @@ function posthogHost() {
   return override || POSTHOG_HOST;
 }
 
-/** True when telemetry must NOT be sent (opt-out envs, CI, dev). */
+/** True when telemetry must NOT be sent (opt-out envs, CI, dev, shared config). */
 export function optedOut() {
   return (
+    // `hyperframes telemetry disable` writes telemetryEnabled: false to the
+    // shared config; one opt-out must cover the CLI and the media-use scripts.
+    readSharedConfig().telemetryEnabled === false ||
     process.env.HYPERFRAMES_NO_TELEMETRY === "1" ||
     process.env.DO_NOT_TRACK === "1" ||
     process.env.CI === "true" ||

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

@@ -57,6 +57,26 @@ test("optedOut respects DO_NOT_TRACK / HYPERFRAMES_NO_TELEMETRY / CI", () => {
   }
 });
 
+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 });
+  }
+});
+
 test("track is a no-op (no network, resolves) when opted out", async () => {
   const savedEnv = { ...process.env };
   const originalFetch = globalThis.fetch;

package/dist/skills/media-use/scripts/transcript-cut.mjs

@@ -98,7 +98,10 @@ function run() {
       // with priming silence (~25-35ms for AAC), which concat then bakes in as a
       // gap at each cut -- a defect distinct from, and surviving, the fades
       // below. PCM has no priming, so audio is encoded exactly once, at concat.
-      const ext = args.copy ? extname(outPath) || ".mp4" : isAudioOnly(outPath) ? ".wav" : ".mkv";
+      // The video container is .mov, not .mkv: ffmpeg writes Matroska
+      // timestamps in whole milliseconds, which moves frames off the source's
+      // frame grid, and the concat copy below carries that into the output.
+      const ext = args.copy ? extname(outPath) || ".mp4" : isAudioOnly(outPath) ? ".wav" : ".mov";
       const out = join(tmpDir, `segment-${String(index).padStart(4, "0")}${ext}`);
       // --copy stays fade-free (stream copy cannot filter). A segment's true
       // start/end (index 0's start, the last segment's end) borders nothing
@@ -183,20 +186,27 @@ function cutSegment(inputPath, segment, outPath, copy, fade) {
     "-y",
     "-nostdin",
     "-ss",
-    fmt(segment.start),
+    seekTime(segment.start),
     "-i",
     inputPath,
     "-to",
-    fmt(segment.end - segment.start),
+    seekTime(segment.end - segment.start),
   ];
   if (copy) {
     argv.push("-c", "copy", "-avoid_negative_ts", "make_zero");
-  } else if (extname(outPath).toLowerCase() === ".mkv") {
+  } else if (extname(outPath).toLowerCase() === ".mov") {
     // Concat splices raw segment edges together; without a short ramp the
     // waveform steps discontinuously at every boundary and you hear a click.
     if (fade) argv.push("-af", fade);
     // Video intermediate: keep the picture cheap and the audio uncompressed.
     argv.push("-c:v", "libx264", "-preset", "veryfast", "-crf", "18", "-c:a", "pcm_s16le");
+    // A keyframe every second. The renderer seeks into this footage, and x264
+    // on its own leaves up to 250 frames between keyframes.
+    argv.push("-force_key_frames", "expr:gte(t,n_forced)");
+    // Constant frame rate from the first frame. Left to itself, ffmpeg 7 starts
+    // a range that begins between two source frames one frame late, and .mov
+    // rounds that lead-in to the millisecond.
+    argv.push("-fps_mode", "cfr");
   } else {
     if (fade) argv.push("-af", fade);
     argv.push("-c:a", "pcm_s16le");
@@ -265,6 +275,15 @@ function fmt(n) {
     .replace(/\.?0+$/, "");
 }
 
+// -ss/-to name frames, and ffmpeg's accurate seek drops everything before the
+// time it is given: at 30 fps, frame 386 sits at 12.866666 s, and a 3-decimal
+// -ss of 12.867 starts that segment on frame 387 instead, leaving the cut a
+// frame short from the join on. So the values ffmpeg gets keep frame precision,
+// while fmt() above stays at 3 decimals for the times that are only printed.
+function seekTime(n) {
+  return Number(n).toFixed(6);
+}
+
 function round3(n) {
   return Math.round(Number(n) * 1000) / 1000;
 }