hyperframes 0.8.111 → 0.8.113

package/dist/{render-DHCMWKFV.js → render-H6RSJF2V.js}

@@ -28,7 +28,7 @@ import {
   reportVariableIssues,
   resolveVariablesArg,
   validateVariablesAgainstProject
-} from "./chunk-CFC3EEDQ.js";
+} from "./chunk-ZMMSMDCA.js";
 import {
   buildPublishFileMap,
   zipPublishFileMap
@@ -38,20 +38,20 @@ import "./chunk-DNXD7TOA.js";
 import "./chunk-WEATBQTR.js";
 import {
   resolveProject
-} from "./chunk-HPEHQUJX.js";
+} from "./chunk-IRJBTYJF.js";
 import {
   errorBox,
   formatBytes,
   formatDuration
 } from "./chunk-IHFUKJOR.js";
 import "./chunk-PFCFR3KZ.js";
-import "./chunk-AMSBTN6L.js";
-import "./chunk-EE6SV6KW.js";
+import "./chunk-7CGIICLA.js";
+import "./chunk-DDK22K3I.js";
 import "./chunk-VWG7OQKU.js";
 import {
   c
 } from "./chunk-ZTZA4UWZ.js";
-import "./chunk-CQRF7VU3.js";
+import "./chunk-L5QASNBN.js";
 import "./chunk-AMKC3AXA.js";
 import {
   defineCommand
@@ -60,16 +60,16 @@ import "./chunk-54HJ63Q2.js";
 import {
   failCommand
 } from "./chunk-PBN6GBJE.js";
-import "./chunk-OF3RKOPU.js";
-import "./chunk-B25H4M4V.js";
+import "./chunk-G2T2X6FZ.js";
+import "./chunk-FCEFKWPM.js";
 import "./chunk-UUDQD62L.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-U4TDAJZE.js";
-import "./chunk-YLVI7VL5.js";
+import "./chunk-OCNCK5FQ.js";
+import "./chunk-C6AIZOQN.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-TWWSYAKJ.js";
-import "./chunk-BAVM2XBR.js";
+import "./chunk-YJEGT5L6.js";
 import "./chunk-HBBJFK6I.js";
 import "./chunk-PJ3HDUCY.js";
 import "./chunk-TQFG7HTI.js";
@@ -77,12 +77,12 @@ import "./chunk-GK4AIFIH.js";
 import "./chunk-2PSPARWP.js";
 import {
   withMeta
-} from "./chunk-Q2QNAFQV.js";
+} from "./chunk-U4VSY56O.js";
 import "./chunk-K4WIOZFP.js";
 import "./chunk-XUXGIA7H.js";
 import "./chunk-WERLJGIC.js";
 import "./chunk-ISN5GRYI.js";
-import "./chunk-YLOSZHA2.js";
+import "./chunk-3XPZJUKM.js";
 import {
   normalizeErrorMessage
 } from "./chunk-KNU5COPB.js";

package/dist/{render-DKXGFQVW.js → render-OKNPNMFS.js}

@@ -6,15 +6,15 @@ var __filename = __hf_fileURLToPath(import.meta.url);
 var __dirname = __hf_dirname(__filename);
 import {
   maybePromptRenderFeedback
-} from "./chunk-ZXSNGIYS.js";
+} from "./chunk-ZZIXIOK2.js";
 import {
   reportVariableIssues,
   resolveVariablesArg,
   validateVariablesAgainstProject
-} from "./chunk-CFC3EEDQ.js";
+} from "./chunk-ZMMSMDCA.js";
 import {
   loadProducer
-} from "./chunk-5ER3PYYP.js";
+} from "./chunk-VLC7JS4K.js";
 import {
   renderJobObservabilityTelemetryPayload
 } from "./chunk-VXVRPIJA.js";
@@ -28,11 +28,11 @@ import {
   resolveBrowserTimeoutMsArg,
   resolveCompositionEntryArg,
   resolveDefaultFpsArg
-} from "./chunk-TIZQC44K.js";
+} from "./chunk-3IUSKIZW.js";
 import "./chunk-YEIFI443.js";
 import {
   resolveProject
-} from "./chunk-HPEHQUJX.js";
+} from "./chunk-IRJBTYJF.js";
 import {
   formatLintStartupMessage
 } from "./chunk-6CSYCFQV.js";
@@ -46,21 +46,21 @@ import {
 } from "./chunk-IHFUKJOR.js";
 import {
   runEnvironmentChecks
-} from "./chunk-E4AYSXMS.js";
+} from "./chunk-E52XEEAA.js";
 import "./chunk-PFCFR3KZ.js";
 import {
   loadProjectConfig,
   readProjectConfigWithStatus,
   seedProjectAuthoringSkill
-} from "./chunk-LAQEZHOH.js";
+} from "./chunk-BOUDTDBQ.js";
 import "./chunk-XT7X6QCP.js";
 import "./chunk-4YYJOFKS.js";
 import {
   normalizeSkillSlug
 } from "./chunk-HVW7ABXD.js";
-import "./chunk-XYVFPDNU.js";
-import "./chunk-HQGJLZB6.js";
-import "./chunk-AWUZ3AUD.js";
+import "./chunk-ENHAGQEP.js";
+import "./chunk-DR7QW6C5.js";
+import "./chunk-IP3XINRB.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-GMECXFAN.js";
 import {
@@ -73,21 +73,21 @@ import {
 } from "./chunk-TVCRUG2S.js";
 import {
   createRenderCancellationScope
-} from "./chunk-JTTAS7N6.js";
+} from "./chunk-7543YIMQ.js";
 import {
   trackRenderComplete,
   trackRenderError,
   trackRenderObservation,
   trackRenderPreflightRejected
-} from "./chunk-AMSBTN6L.js";
-import "./chunk-EE6SV6KW.js";
+} from "./chunk-7CGIICLA.js";
+import "./chunk-DDK22K3I.js";
 import "./chunk-VWG7OQKU.js";
 import {
   c
 } from "./chunk-ZTZA4UWZ.js";
 import {
   bytesToMb
-} from "./chunk-CQRF7VU3.js";
+} from "./chunk-L5QASNBN.js";
 import "./chunk-AMKC3AXA.js";
 import {
   markRenderSucceeded,
@@ -109,13 +109,13 @@ import {
   MAX_VP9_CPU_USED,
   MIN_VP9_CPU_USED,
   isVideoFrameFormat
-} from "./chunk-OF3RKOPU.js";
+} from "./chunk-G2T2X6FZ.js";
 import {
   formatRenderOutputTimestamp,
   fpsToFfmpegArg,
   fpsToNumber,
   parseFps
-} from "./chunk-B25H4M4V.js";
+} from "./chunk-FCEFKWPM.js";
 import {
   checkOutputResolutionCompatibility,
   isAspectAgnosticResolutionAlias,
@@ -123,14 +123,14 @@ import {
   suggestMatchingPreset
 } from "./chunk-UUDQD62L.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-U4TDAJZE.js";
-import "./chunk-YLVI7VL5.js";
+import "./chunk-OCNCK5FQ.js";
+import "./chunk-C6AIZOQN.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-OFQWTKPW.js";
 import {
   hasDefinitiveEntryMismatch
 } from "./chunk-Q5X2B5WT.js";
-import "./chunk-N34BYX3E.js";
+import "./chunk-4PFZPP2N.js";
 import {
   killOrphanedProcessesForRender
 } from "./chunk-LAOCA3MQ.js";
@@ -142,7 +142,7 @@ import {
   collectSubCompositionSrcs,
   lintProject,
   shouldBlockRender
-} from "./chunk-BAVM2XBR.js";
+} from "./chunk-YJEGT5L6.js";
 import "./chunk-HBBJFK6I.js";
 import "./chunk-PJ3HDUCY.js";
 import "./chunk-TQFG7HTI.js";
@@ -161,7 +161,7 @@ import {
 } from "./chunk-ISN5GRYI.js";
 import {
   VERSION
-} from "./chunk-YLOSZHA2.js";
+} from "./chunk-3XPZJUKM.js";
 import {
   normalizeErrorMessage
 } from "./chunk-KNU5COPB.js";
@@ -659,7 +659,7 @@ async function executeRenderPlan(plan, dependencies, cancellation) {
   let batchModule;
   let preparedBatch;
   if (plan.batchPath) {
-    batchModule = await import("./batchRender-ZTHFMHZY.js");
+    batchModule = await import("./batchRender-QVJ7NEUH.js");
     try {
       preparedBatch = batchModule.prepareBatchRender({
         batchPath: plan.batchPath,
@@ -748,7 +748,7 @@ function assertRenderActive(cancellation) {
   cancellation?.signal.throwIfAborted();
 }
 async function ensureRenderBrowser(plan, signal) {
-  const { ensureBrowser } = await import("./manager-NEVLEZK3.js");
+  const { ensureBrowser } = await import("./manager-CT3D67CG.js");
   let browserSpinner;
   try {
     if (plan.effectiveQuiet) {

package/dist/{render-4C3YKVZI.js → render-TGCDBKMP.js}

@@ -15,7 +15,7 @@ import {
   reportVariableIssues,
   resolveVariablesArg,
   validateVariablesAgainstProject
-} from "./chunk-CFC3EEDQ.js";
+} from "./chunk-ZMMSMDCA.js";
 import "./chunk-5Z63TBTX.js";
 import "./chunk-IHFUKJOR.js";
 import "./chunk-PFCFR3KZ.js";
@@ -25,10 +25,10 @@ import {
 import {
   setCommandExitCode
 } from "./chunk-PBN6GBJE.js";
-import "./chunk-B25H4M4V.js";
+import "./chunk-FCEFKWPM.js";
 import "./chunk-UUDQD62L.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-YLVI7VL5.js";
+import "./chunk-C6AIZOQN.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-TQFG7HTI.js";

package/dist/{render-batch-AFDBPDMM.js → render-batch-WRQFW4UC.js}

@@ -14,7 +14,7 @@ import {
   loadProjectVariableSchema,
   reportVariableIssues,
   validateVariablesAgainstSchema
-} from "./chunk-CFC3EEDQ.js";
+} from "./chunk-ZMMSMDCA.js";
 import "./chunk-5Z63TBTX.js";
 import {
   errorBox
@@ -27,10 +27,10 @@ import {
   failCommand,
   setCommandExitCode
 } from "./chunk-PBN6GBJE.js";
-import "./chunk-B25H4M4V.js";
+import "./chunk-FCEFKWPM.js";
 import "./chunk-UUDQD62L.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-YLVI7VL5.js";
+import "./chunk-C6AIZOQN.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-TQFG7HTI.js";

package/dist/{renderCancellation-VIZELWDD.js → renderCancellation-BFCQYGVV.js}

@@ -7,19 +7,19 @@ var __dirname = __hf_dirname(__filename);
 import {
   createRenderCancellationScope,
   stoppedByCancelSignal
-} from "./chunk-JTTAS7N6.js";
-import "./chunk-OF3RKOPU.js";
-import "./chunk-B25H4M4V.js";
+} from "./chunk-7543YIMQ.js";
+import "./chunk-G2T2X6FZ.js";
+import "./chunk-FCEFKWPM.js";
 import "./chunk-UUDQD62L.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-U4TDAJZE.js";
-import "./chunk-YLVI7VL5.js";
+import "./chunk-OCNCK5FQ.js";
+import "./chunk-C6AIZOQN.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-LAOCA3MQ.js";
 import "./chunk-LCSMOLGX.js";
 import "./chunk-TWWSYAKJ.js";
-import "./chunk-BAVM2XBR.js";
+import "./chunk-YJEGT5L6.js";
 import "./chunk-HBBJFK6I.js";
 import "./chunk-PJ3HDUCY.js";
 import "./chunk-TQFG7HTI.js";

package/dist/renderSetupWorker.js

@@ -8,7 +8,7 @@ import "./chunk-Q5X2B5WT.js";
 import {
   ensureBrowser,
   releaseOwnedBrowserInstallLock
-} from "./chunk-N34BYX3E.js";
+} from "./chunk-4PFZPP2N.js";
 import {
   killOrphanedProcesses
 } from "./chunk-LAOCA3MQ.js";
@@ -16,7 +16,7 @@ import "./chunk-LCSMOLGX.js";
 import "./chunk-TWWSYAKJ.js";
 import {
   lintProject
-} from "./chunk-BAVM2XBR.js";
+} from "./chunk-YJEGT5L6.js";
 import "./chunk-HBBJFK6I.js";
 import "./chunk-PJ3HDUCY.js";
 import "./chunk-TQFG7HTI.js";

package/dist/{resolver-S72XBTEQ.js → resolver-37UOGAMT.js}

@@ -11,14 +11,14 @@ import {
   resolveItemWithDependencies,
   resolveItemsByTag,
   unreachableRegistryMessage
-} from "./chunk-XYVFPDNU.js";
-import "./chunk-AWUZ3AUD.js";
+} from "./chunk-ENHAGQEP.js";
+import "./chunk-IP3XINRB.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-GMECXFAN.js";
-import "./chunk-B25H4M4V.js";
+import "./chunk-FCEFKWPM.js";
 import "./chunk-UUDQD62L.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-YLVI7VL5.js";
+import "./chunk-C6AIZOQN.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-TQFG7HTI.js";

package/dist/{screenshotCapture-FA5HPN7Q.js → screenshotCapture-ECBTLCU6.js}

@@ -8,12 +8,12 @@ import {
   isDegradableEvaluateTimeoutError
 } from "./chunk-AWNBM3MZ.js";
 import {
+  ensureCaptureDirSync,
   writeCaptureFileSync
-} from "./chunk-5GQAJ43Q.js";
+} from "./chunk-MRF4AMKD.js";
 import "./chunk-M2WBOQ2Q.js";
 
 // src/capture/screenshotCapture.ts
-import { mkdirSync } from "fs";
 import { join } from "path";
 var MAX_PLATE_HEIGHT_PX = 16384;
 function pngHeight(buf) {
@@ -56,7 +56,7 @@ async function captureFullPagePlate(page, screenshotsDir, budget = {}) {
 }
 async function captureScrollScreenshots(page, outputDir, budget = {}) {
   const screenshotsDir = join(outputDir, "screenshots");
-  mkdirSync(screenshotsDir, { recursive: true });
+  ensureCaptureDirSync(outputDir, screenshotsDir);
   const MAX_SCREENSHOTS = 20;
   const filePaths = [];
   if ((budget.remainingMs?.() ?? 1) <= 0) return filePaths;

package/dist/{sherpa-BAADWCHB.js → sherpa-SDVKYXCX.js}

@@ -11,26 +11,26 @@ import "./chunk-WEATBQTR.js";
 import {
   getPreparedWavDurationSeconds,
   prepareWav
-} from "./chunk-I5WWEBDG.js";
+} from "./chunk-HTQR7SUZ.js";
 import "./chunk-OAF4XJOW.js";
 import "./chunk-X5HWXQPU.js";
 import "./chunk-TVCRUG2S.js";
 import {
   stoppedByCancelSignal
-} from "./chunk-JTTAS7N6.js";
+} from "./chunk-7543YIMQ.js";
 import "./chunk-AMKC3AXA.js";
-import "./chunk-OF3RKOPU.js";
-import "./chunk-B25H4M4V.js";
+import "./chunk-G2T2X6FZ.js";
+import "./chunk-FCEFKWPM.js";
 import "./chunk-UUDQD62L.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-U4TDAJZE.js";
-import "./chunk-YLVI7VL5.js";
+import "./chunk-OCNCK5FQ.js";
+import "./chunk-C6AIZOQN.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-LAOCA3MQ.js";
 import "./chunk-LCSMOLGX.js";
 import "./chunk-TWWSYAKJ.js";
-import "./chunk-BAVM2XBR.js";
+import "./chunk-YJEGT5L6.js";
 import "./chunk-HBBJFK6I.js";
 import "./chunk-PJ3HDUCY.js";
 import "./chunk-TQFG7HTI.js";

package/dist/skills/hyperframes/references/frame-worker-core.md

@@ -17,9 +17,9 @@ You build the frame composition file(s) assigned in your dispatch and nothing el
   - `blueprint:` — an id (or the literal `compose`): the shot template this frame instantiates — the overall shape + its signature move. Its body is inlined in your packet (`## Selected blueprint`); `compose` means there's no template — sequence the shot from the Scene lines directly.
   - `focal:` / `roles:` — which element is the hero and what each element is. **Semantics are workflow-specific — see the delta.**
   - `sfx:` — the orchestrator's; you mount no audio.
-- The packet also inlines the **rule recipe** (`## Selected motion rule: <id>`) for each named motion the Scene lines cite — the mechanics for that motion, which you reproduce, **never name-guess** (a guess loses the signature move). If a cited motion's recipe is missing from your packet, read `RULES_DIR/<id>.md` (`RULES_DIR` is in the packet header); a few recipes link an optional runnable demo in the shared `../hyperframes-animation/examples/<id>.html` — open it only when a recipe is unclear.
+- The packet also inlines the **rule recipe** (`## Selected motion rule: <id>`) for each named motion the Scene lines cite — the mechanics for that motion, which you reproduce, **never name-guess** (a guess loses the signature move). If a cited motion's recipe is missing from your packet, read `RULES_DIR/<id>.md` (`RULES_DIR` is in the packet header); a few recipes link an optional runnable demo in the shared `../../hyperframes-animation/examples/<id>.html` — open it only when a recipe is unclear.
 - `frame.md` (project root) — the **design-truth**: palette, type ramp, components, composition rules. The LOOK. Pull every visual token from here. This is the one file you read outside your packet.
-- `../references/cut-catalog.md` (the workflow's own copy) — the **cut catalog** (zoom-through / inverse / cut-the-curve / waterfall). When a Scene seam is a within-scene swap, a scene-to-scene cut, or a text-to-text line change, build it INSIDE your composition per this catalog (Z-scale + blur + opacity, or per-word x-staggers). You never author the between-frame transition — story's `transition_in` + the injector own that.
+- `references/cut-catalog.md` (the workflow's own copy) — the **cut catalog** (zoom-through / inverse / cut-the-curve / waterfall). When a Scene seam is a within-scene swap, a scene-to-scene cut, or a text-to-text line change, build it INSIDE your composition per this catalog (Z-scale + blur + opacity, or per-word x-staggers). You never author the between-frame transition — story's `transition_in` + the injector own that.
 - Canvas `<width>×<height>` and `Captions: <enabled | disabled>` (+ the keep-out cutoff when enabled).
 
 **Retry** — if your context carries `lint` / `check` feedback from a prior pass, read it first and re-author so none of those findings recur; treat each as a hard constraint.

package/dist/skills/hyperframes-cli/references/lint-validate-inspect.md

@@ -30,7 +30,7 @@ Lints `index.html` and all files in `compositions/`. Reports errors (must fix),
 ```bash
 npx hyperframes check                    # current directory: the full browser gate
 npx hyperframes check ./my-project       # specific project
-npx hyperframes check --json             # agent-readable envelope {ok, lint, runtime, layout, motion, contrast, hdr, snapshots}
+npx hyperframes check --json             # agent-readable envelope {ok, browserSkipped, lint, runtime, layout, motion, contrast, hdr, snapshots}
 npx hyperframes check --snapshots        # also write overview frames (annotated) + per-finding crops
 npx hyperframes check --samples 15       # denser timeline sweep (default 9)
 npx hyperframes check --at 1.5,4,7.25    # explicit hero-frame timestamps
@@ -41,7 +41,7 @@ npx hyperframes check --no-contrast      # skip the WCAG audit while iterating
 npx hyperframes check --strict           # exit non-zero on warnings too (default: only errors)
 ```
 
-One command, one Chrome boot. `check` runs the linter first and skips the browser entirely when lint reports errors. Then it loads the bundled composition once, wires runtime listeners before navigation, and sweeps one seek grid running every audit per sample:
+One command, one Chrome boot. `check` runs the linter first and skips the browser entirely when lint reports errors. When the browser never ran (lint errors, a linter crash, or a browser launch failure), `browserSkipped` is `true` and the `layout`, `motion` and `contrast` sections are empty, not clean. Otherwise it loads the bundled composition once, wires runtime listeners before navigation, and sweeps one seek grid running every audit per sample:
 
 - **Runtime**: JavaScript console errors, unhandled exceptions, failed network requests (media-file `ERR_ABORTED` filtered out), HTTP 4xx/5xx.
 - **Layout**: text extending outside its container or the canvas, text clipped by its own box, held text overlaps and occlusion (with an approximate covered fraction), children escaping clipping containers.

package/dist/skills/media-use/audio/references/bgm.md

@@ -5,7 +5,7 @@ One music bed per composition, produced by the shared audio engine (`scripts/aud
 - **HeyGen retrieval — the default when credentialed.** Search HeyGen's music catalog by mood, download the top track. No generation; same `~/.heygen` / `$HEYGEN_API_KEY` credential as TTS.
 - **Local generation (Lyria → MusicGen) — the fallback when there is no credential** (or when asked for explicitly). Generate a WAV from a mood prompt. There is **no `npx hyperframes bgm` command**; the engine spawns `scripts/lyria-recipe.py` or an inline MusicGen script directly.
 
-> **Run the Preflight first — no credential is not a green light to silently generate locally.** Before generating, complete the sign-in **Preflight** (see `../SKILL.md` → Preflight): run `npx hyperframes auth status`, recommend signing in, and **STOP for the user's choice** (sign in for HeyGen's music library, or continue offline with local generation). This applies to a one-off "generate a BGM" request just as much as inside a full workflow.
+> **Run the Preflight first — no credential is not a green light to silently generate locally.** Before generating, complete the sign-in **Preflight** (see `../../SKILL.md` → Preflight): run `npx hyperframes auth status`, recommend signing in, and **STOP for the user's choice** (sign in for HeyGen's music library, or continue offline with local generation). This applies to a one-off "generate a BGM" request just as much as inside a full workflow.
 
 ## Driving it from the request
 

package/dist/skills/media-use/audio/references/tts.md

@@ -4,7 +4,7 @@
 `--provider` or `--words` flag. For HeyGen audio plus word timestamps, use the
 bundled `heygen-tts.mjs` script below.
 
-> **Run the Preflight first — no credential is not a green light to silently use the local voice.** Before generating a voiceover, complete the sign-in **Preflight** (see `../SKILL.md` → Preflight): run `npx hyperframes auth status`, recommend signing in, and **STOP for the user's choice** (sign in for HeyGen voices, or continue offline with local Kokoro). This applies to a one-off "generate a voiceover" request just as much as inside a full workflow.
+> **Run the Preflight first — no credential is not a green light to silently use the local voice.** Before generating a voiceover, complete the sign-in **Preflight** (see `../../SKILL.md` → Preflight): run `npx hyperframes auth status`, recommend signing in, and **STOP for the user's choice** (sign in for HeyGen voices, or continue offline with local Kokoro). This applies to a one-off "generate a voiceover" request just as much as inside a full workflow.
 
 ## Narrating a HyperFrames docs video
 

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

@@ -11,12 +11,20 @@
 // Resolve once, per process: probe the platform's candidates in order and take
 // the first that actually runs. `py` is the launcher, so it needs a `-3` arg to
 // select Python 3 — hence candidates are argv PREFIXES, not bare names.
+//
+// `HYPERFRAMES_PYTHON` (the documented PEP 668 venv setup) wins over the PATH probe, matching
+// the CLI's `findPython()`; ignoring it made BGM silently disable itself (#4614).
 
 import { spawnSync } from "node:child_process";
 
-function defaultProbe(cmd, args) {
+// Accept only an interpreter whose `--version` reports Python 3, as the CLI's
+// `validatePythonOverride()` does. Exit status alone would take a Python 2
+// `python` (or any executable that exits 0) that `doctor` rejects. Python 2
+// prints its version to stderr, so read both streams.
+export function defaultProbe(cmd, args) {
   try {
-    return spawnSync(cmd, args, { stdio: "ignore" }).status === 0;
+    const result = spawnSync(cmd, args, { encoding: "utf-8", timeout: 5000 });
+    return result.status === 0 && /Python 3/.test(`${result.stdout}${result.stderr}`);
   } catch {
     return false;
   }
@@ -26,12 +34,18 @@ function defaultProbe(cmd, args) {
  * Pick the argv prefix that launches Python 3 on this platform.
  * Returns e.g. `["python3"]`, `["python"]`, or `["py", "-3"]`.
  *
- * Pure except for `probe` (which runs `<cmd> … --version`); both `platform`
- * and `probe` are injectable so every branch is unit-testable without spawning.
+ * Pure except for `probe` (which runs `<cmd> … --version`); `platform`, `probe`
+ * and `env` are injectable so every branch is unit-testable without spawning.
  * If nothing probes OK, falls back to the canonical name for the platform so
  * the eventual spawn fails loudly exactly as it did before — never worse.
  */
-export function resolvePythonCommand(platform = process.platform, probe = defaultProbe) {
+export function resolvePythonCommand(
+  platform = process.platform,
+  probe = defaultProbe,
+  env = process.env,
+) {
+  const override = env.HYPERFRAMES_PYTHON;
+  if (override && probe(override, ["--version"])) return [override];
   const candidates =
     platform === "win32" ? [["python3"], ["python"], ["py", "-3"]] : [["python3"], ["python"]];
   for (const prefix of candidates) {

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

@@ -1,6 +1,9 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { resolvePythonCommand, pythonInvocation } from "./python.mjs";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { defaultProbe, resolvePythonCommand, pythonInvocation } from "./python.mjs";
 
 // Regression: on Windows a standard python.org install has no `python3.exe`
 // (only `python.exe` + the `py` launcher), so `spawn("python3", …)` ENOENTs and
@@ -55,6 +58,71 @@ test("falls back to the canonical name (loud failure, unchanged) when nothing ru
   );
 });
 
+// Regression (#4614): on PEP 668 systems the documented setup is a venv named
+// by HYPERFRAMES_PYTHON; the audio engine ignored it and probed the bare
+// system python3, so MusicGen BGM was skipped while `doctor` said installed.
+const VENV = "/home/u/.venvs/hf/bin/python";
+
+test("HYPERFRAMES_PYTHON wins over python3 on PATH when it runs", () => {
+  const env = { HYPERFRAMES_PYTHON: VENV };
+  assert.deepEqual(resolvePythonCommand("darwin", probeFor(VENV, "python3"), env), [VENV]);
+  assert.deepEqual(resolvePythonCommand("win32", probeFor(VENV, "python", "py"), env), [VENV]);
+});
+
+test("a HYPERFRAMES_PYTHON that doesn't run falls through to the PATH probe", () => {
+  const env = { HYPERFRAMES_PYTHON: "/nope/python" };
+  assert.deepEqual(resolvePythonCommand("linux", probeFor("python3"), env), ["python3"]);
+});
+
+test("an empty HYPERFRAMES_PYTHON is ignored without being probed", () => {
+  const seen = [];
+  const probe = (cmd) => {
+    seen.push(cmd);
+    return cmd === "python3";
+  };
+  assert.deepEqual(resolvePythonCommand("linux", probe, { HYPERFRAMES_PYTHON: "" }), ["python3"]);
+  assert.deepEqual(seen, ["python3"]);
+});
+
+// defaultProbe must match the CLI's validatePythonOverride(): exiting 0 is not
+// enough, `--version` has to report Python 3. Stubs are shell scripts, so
+// these run on POSIX only.
+function withStub(script, fn) {
+  const dir = mkdtempSync(join(tmpdir(), "hf-python-probe-"));
+  try {
+    const stub = join(dir, "python");
+    writeFileSync(stub, `#!/bin/sh\n${script}\n`);
+    chmodSync(stub, 0o755);
+    fn(stub);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const posixOnly = { skip: process.platform === "win32" && "stub scripts need a POSIX shell" };
+
+test("defaultProbe accepts an interpreter reporting Python 3", posixOnly, () => {
+  withStub('echo "Python 3.12.4"', (stub) => assert.equal(defaultProbe(stub, ["--version"]), true));
+});
+
+test("defaultProbe rejects Python 2, which prints its version to stderr", posixOnly, () => {
+  withStub('echo "Python 2.7.18" >&2', (stub) =>
+    assert.equal(defaultProbe(stub, ["--version"]), false),
+  );
+});
+
+test(
+  "defaultProbe rejects an executable that exits 0 without a Python 3 version",
+  posixOnly,
+  () => {
+    withStub("exit 0", (stub) => assert.equal(defaultProbe(stub, ["--version"]), false));
+  },
+);
+
+test("defaultProbe rejects a command that doesn't exist", () => {
+  assert.equal(defaultProbe("/nonexistent/hf-python", ["--version"]), false);
+});
+
 test("pythonInvocation prepends the resolved prefix ahead of caller args", () => {
   assert.deepEqual(pythonInvocation(["-c", "import x"], ["python"]), {
     cmd: "python",