hyperframes 0.8.121 → 0.8.123

package/dist/{render-BYD7ZASF.js → render-SGKRP4OI.js}

@@ -6,36 +6,37 @@ var __filename = __hf_fileURLToPath(import.meta.url);
 var __dirname = __hf_dirname(__filename);
 import {
   maybePromptRenderFeedback
-} from "./chunk-RYSHGEZL.js";
+} from "./chunk-MUAFAG77.js";
 import {
   reportVariableIssues,
   resolveVariablesArg,
   validateVariablesAgainstProject
-} from "./chunk-WW7V2GQJ.js";
+} from "./chunk-AICUP6TU.js";
 import {
   loadProducer
-} from "./chunk-XLG5C3XA.js";
+} from "./chunk-4EZKLNMD.js";
 import {
   formatLintStartupMessage
 } from "./chunk-6CSYCFQV.js";
 import {
   resolveProject
-} from "./chunk-WBRDOH4A.js";
+} from "./chunk-UI2I6ZQE.js";
 import {
   renderJobObservabilityTelemetryPayload
 } from "./chunk-VXVRPIJA.js";
-import {
-  windowsChromeCrashRemediation
-} from "./chunk-262C25DQ.js";
 import {
   hasExplicitCompositionArg,
   parseGifLoopArg,
   parseHlsSegmentSecondsArg,
   resolveBrowserTimeoutMsArg,
   resolveCompositionEntryArg,
-  resolveDefaultFpsArg
-} from "./chunk-5OS5XIWZ.js";
+  resolveDefaultFpsArg,
+  windowsChromeCrashRemediation
+} from "./chunk-2QAAOW5T.js";
 import "./chunk-YEIFI443.js";
+import {
+  desktopHint
+} from "./chunk-AMV2OPXR.js";
 import {
   errorBox,
   formatBytes,
@@ -46,24 +47,24 @@ import {
 } from "./chunk-IHFUKJOR.js";
 import {
   runEnvironmentChecks
-} from "./chunk-VU4KRDRL.js";
+} from "./chunk-PUFPAYTJ.js";
 import "./chunk-PFCFR3KZ.js";
 import {
   createRenderCancellationScope
-} from "./chunk-LZN67SFR.js";
+} from "./chunk-RTINVJNS.js";
 import {
   loadProjectConfig,
   readProjectConfigWithStatus,
   seedProjectAuthoringSkill
-} from "./chunk-3WXWL7AY.js";
+} from "./chunk-MBSCHJQZ.js";
 import "./chunk-XT7X6QCP.js";
 import "./chunk-4YYJOFKS.js";
 import {
   normalizeSkillSlug
 } from "./chunk-HVW7ABXD.js";
-import "./chunk-JACPHNUK.js";
-import "./chunk-KYDM3W7A.js";
-import "./chunk-ZBMQOBQK.js";
+import "./chunk-BET5FXMM.js";
+import "./chunk-E26WHQFM.js";
+import "./chunk-XIJTGR4O.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-P6LJ4Y32.js";
 import "./chunk-GMECXFAN.js";
@@ -80,15 +81,15 @@ import {
   trackRenderError,
   trackRenderObservation,
   trackRenderPreflightRejected
-} from "./chunk-NPHNGWJH.js";
-import "./chunk-6WIWCYD5.js";
+} from "./chunk-7NWNDQID.js";
+import "./chunk-S3JOM6L4.js";
 import "./chunk-VWG7OQKU.js";
 import {
   c
 } from "./chunk-ZTZA4UWZ.js";
 import {
   bytesToMb
-} from "./chunk-BN5KOC5O.js";
+} from "./chunk-ILOJE2TE.js";
 import "./chunk-AMKC3AXA.js";
 import {
   markRenderSucceeded,
@@ -110,22 +111,22 @@ import {
   MAX_VP9_CPU_USED,
   MIN_VP9_CPU_USED,
   isVideoFrameFormat
-} from "./chunk-MNMD6XLG.js";
+} from "./chunk-WAD4ACBZ.js";
 import {
   formatRenderOutputTimestamp,
   fpsToFfmpegArg,
   fpsToNumber,
   parseFps
-} from "./chunk-RCNDZEBU.js";
+} from "./chunk-TLA5RBEB.js";
 import {
   checkOutputResolutionCompatibility,
   isAspectAgnosticResolutionAlias,
   normalizeResolutionFlag,
   suggestMatchingPreset
-} from "./chunk-FSLYPQ5Z.js";
+} from "./chunk-F7MXHGU3.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-GPGWCFIA.js";
-import "./chunk-PATLRNZA.js";
+import "./chunk-RYP46ARK.js";
+import "./chunk-53IO4HLZ.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-OFQWTKPW.js";
 import {
@@ -143,7 +144,7 @@ import {
   collectSubCompositionSrcs,
   lintProject,
   shouldBlockRender
-} from "./chunk-NITBGIHR.js";
+} from "./chunk-N4RVOW43.js";
 import "./chunk-HBBJFK6I.js";
 import "./chunk-PJ3HDUCY.js";
 import "./chunk-TQFG7HTI.js";
@@ -162,7 +163,7 @@ import {
 } from "./chunk-ISN5GRYI.js";
 import {
   VERSION
-} from "./chunk-WG4IZWEH.js";
+} from "./chunk-XQSMY5HF.js";
 import {
   normalizeErrorMessage
 } from "./chunk-KNU5COPB.js";
@@ -660,7 +661,7 @@ async function executeRenderPlan(plan, dependencies, cancellation) {
   let batchModule;
   let preparedBatch;
   if (plan.batchPath) {
-    batchModule = await import("./batchRender-2HXYPO62.js");
+    batchModule = await import("./batchRender-JDH4PXPD.js");
     try {
       preparedBatch = batchModule.prepareBatchRender({
         batchPath: plan.batchPath,
@@ -850,9 +851,9 @@ async function runResolutionPreflight(plan, checkResolution) {
   errorBox("Output resolution incompatible", issue.message);
   failCommand();
 }
-async function executeBatchRender(plan, browserPath, batchModule, preparedBatch, dependencies, cancellation) {
+function batchRowRenderOptions(plan, browserPath) {
   const batchQuiet = plan.quiet || plan.batchJson;
-  const renderOptionsBase = {
+  return {
     fps: plan.fps,
     quality: plan.quality,
     authoringSkill: plan.authoringSkill,
@@ -888,8 +889,13 @@ async function executeBatchRender(plan, browserPath, batchModule, preparedBatch,
     exitAfterComplete: false,
     throwOnError: true,
     skipFeedback: true,
+    desktopHint: false,
     manageDeParallelRouterBreaker: plan.batchConcurrency <= 1
   };
+}
+async function executeBatchRender(plan, browserPath, batchModule, preparedBatch, dependencies, cancellation) {
+  const batchQuiet = plan.quiet || plan.batchJson;
+  const renderOptionsBase = batchRowRenderOptions(plan, browserPath);
   const manifest = await batchModule.runBatchRender({
     prepared: preparedBatch,
     concurrency: plan.batchConcurrency,
@@ -1653,6 +1659,8 @@ async function renderDocker(projectDir, outputPath, options) {
     "printRenderComplete",
     () => printRenderComplete({
       outputPath,
+      projectDir,
+      desktopHint: wantsDesktopHint(options),
       elapsedMs: elapsed,
       quiet: options.quiet,
       format: options.format
@@ -1855,6 +1863,8 @@ async function executeLocalRender(projectDir, outputPath, options, cancellation)
     "printRenderComplete",
     () => printRenderComplete({
       outputPath,
+      projectDir,
+      desktopHint: wantsDesktopHint(options),
       elapsedMs: elapsed,
       quiet: options.quiet,
       format: options.format,
@@ -2301,6 +2311,9 @@ function readOutputFootprint(outputPath) {
     return { fileSize: "unknown", isDirectory: false };
   }
 }
+function wantsDesktopHint(options) {
+  return options.desktopHint !== false && options.quality !== "draft";
+}
 function printRenderComplete(input) {
   if (input.quiet) return;
   const { outputPath, elapsedMs, perf } = input;
@@ -2316,6 +2329,8 @@ function printRenderComplete(input) {
   console.log(c.success("\u25C7") + "  " + c.accent(outputPath));
   console.log("   " + c.bold(fileSize) + c.dim(" \xB7 " + detail));
   if (perf) printRenderPipeline(perf, input.requestedGpuMode);
+  const hint = input.desktopHint ? desktopHint(input.projectDir) : null;
+  if (hint) console.log("   " + c.dim(hint));
 }
 function printRenderPipeline(perf, requestedGpuMode) {
   const capture = {
@@ -2347,5 +2362,6 @@ export {
   renderLintContinuationHint,
   renderLocal,
   resolveBrowserGpuForCli,
-  runRenderLint
+  runRenderLint,
+  wantsDesktopHint
 };

package/dist/{render-NRNF56OV.js → render-WWSM5VDX.js}

@@ -15,7 +15,7 @@ import {
   reportVariableIssues,
   resolveVariablesArg,
   validateVariablesAgainstProject
-} from "./chunk-WW7V2GQJ.js";
+} from "./chunk-AICUP6TU.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-RCNDZEBU.js";
-import "./chunk-FSLYPQ5Z.js";
+import "./chunk-TLA5RBEB.js";
+import "./chunk-F7MXHGU3.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-PATLRNZA.js";
+import "./chunk-53IO4HLZ.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-TQFG7HTI.js";

package/dist/{render-batch-L2AIXYA3.js → render-batch-UHVLIDQ6.js}

@@ -14,7 +14,7 @@ import {
   loadProjectVariableSchema,
   reportVariableIssues,
   validateVariablesAgainstSchema
-} from "./chunk-WW7V2GQJ.js";
+} from "./chunk-AICUP6TU.js";
 import "./chunk-5Z63TBTX.js";
 import {
   errorBox
@@ -27,10 +27,10 @@ import {
   failCommand,
   setCommandExitCode
 } from "./chunk-PBN6GBJE.js";
-import "./chunk-RCNDZEBU.js";
-import "./chunk-FSLYPQ5Z.js";
+import "./chunk-TLA5RBEB.js";
+import "./chunk-F7MXHGU3.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-PATLRNZA.js";
+import "./chunk-53IO4HLZ.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-TQFG7HTI.js";

package/dist/{renderCancellation-XR3W2AQT.js → renderCancellation-TZ2YQXLI.js}

@@ -7,19 +7,19 @@ var __dirname = __hf_dirname(__filename);
 import {
   createRenderCancellationScope,
   stoppedByCancelSignal
-} from "./chunk-LZN67SFR.js";
-import "./chunk-MNMD6XLG.js";
-import "./chunk-RCNDZEBU.js";
-import "./chunk-FSLYPQ5Z.js";
+} from "./chunk-RTINVJNS.js";
+import "./chunk-WAD4ACBZ.js";
+import "./chunk-TLA5RBEB.js";
+import "./chunk-F7MXHGU3.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-GPGWCFIA.js";
-import "./chunk-PATLRNZA.js";
+import "./chunk-RYP46ARK.js";
+import "./chunk-53IO4HLZ.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-LAOCA3MQ.js";
 import "./chunk-LCSMOLGX.js";
 import "./chunk-TWWSYAKJ.js";
-import "./chunk-NITBGIHR.js";
+import "./chunk-N4RVOW43.js";
 import "./chunk-HBBJFK6I.js";
 import "./chunk-PJ3HDUCY.js";
 import "./chunk-TQFG7HTI.js";

package/dist/renderSetupWorker.js

@@ -16,7 +16,7 @@ import "./chunk-LCSMOLGX.js";
 import "./chunk-TWWSYAKJ.js";
 import {
   lintProject
-} from "./chunk-NITBGIHR.js";
+} from "./chunk-N4RVOW43.js";
 import "./chunk-HBBJFK6I.js";
 import "./chunk-PJ3HDUCY.js";
 import "./chunk-TQFG7HTI.js";

package/dist/{resolver-RYPIAEGU.js → resolver-BERTN5TY.js}

@@ -11,15 +11,15 @@ import {
   resolveItemWithDependencies,
   resolveItemsByTag,
   unreachableRegistryMessage
-} from "./chunk-JACPHNUK.js";
-import "./chunk-ZBMQOBQK.js";
+} from "./chunk-BET5FXMM.js";
+import "./chunk-XIJTGR4O.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-P6LJ4Y32.js";
 import "./chunk-GMECXFAN.js";
-import "./chunk-RCNDZEBU.js";
-import "./chunk-FSLYPQ5Z.js";
+import "./chunk-TLA5RBEB.js";
+import "./chunk-F7MXHGU3.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-PATLRNZA.js";
+import "./chunk-53IO4HLZ.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-TQFG7HTI.js";

package/dist/{sherpa-MXQ34FFS.js → sherpa-WAI3BU35.js}

@@ -11,26 +11,26 @@ import "./chunk-EOVYQ3IG.js";
 import {
   getPreparedWavDurationSeconds,
   prepareWav
-} from "./chunk-AA4KEZGW.js";
+} from "./chunk-EJF6CESB.js";
 import {
   stoppedByCancelSignal
-} from "./chunk-LZN67SFR.js";
+} from "./chunk-RTINVJNS.js";
 import "./chunk-OAF4XJOW.js";
 import "./chunk-X5HWXQPU.js";
 import "./chunk-TVCRUG2S.js";
 import "./chunk-AMKC3AXA.js";
-import "./chunk-MNMD6XLG.js";
-import "./chunk-RCNDZEBU.js";
-import "./chunk-FSLYPQ5Z.js";
+import "./chunk-WAD4ACBZ.js";
+import "./chunk-TLA5RBEB.js";
+import "./chunk-F7MXHGU3.js";
 import "./chunk-DPVXBVLL.js";
-import "./chunk-GPGWCFIA.js";
-import "./chunk-PATLRNZA.js";
+import "./chunk-RYP46ARK.js";
+import "./chunk-53IO4HLZ.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-LAOCA3MQ.js";
 import "./chunk-LCSMOLGX.js";
 import "./chunk-TWWSYAKJ.js";
-import "./chunk-NITBGIHR.js";
+import "./chunk-N4RVOW43.js";
 import "./chunk-HBBJFK6I.js";
 import "./chunk-PJ3HDUCY.js";
 import "./chunk-TQFG7HTI.js";

package/dist/skills/media-use/SKILL.md

@@ -11,6 +11,8 @@ The media OS for HyperFrames: resolve · generate · operate · remember — eve
 
 First run: install and sign in to the `heygen` CLI (the free-usage path), then verify with `npx hyperframes media-use resolve --doctor`. Setup and providers: `references/setup-providers.md`.
 
+Before generating a voiceover or an avatar video, tell the person: signing in to the heygen CLI with OAuth (`heygen auth login --oauth`) gives a free allowance for TTS voiceover and avatar videos, while an API key bills API credits.
+
 ## Resolve — the one verb
 
 ```bash

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

@@ -59,23 +59,29 @@ export function loadEnvFromDir(startDir) {
 
 // → { headers } | { expired: true } | null. Never throws.
 export function heygenCredential() {
+  const cred = resolveCredential();
+  return cred?.unreadable ? null : cred;
+}
+
+// heygenCredential's answer, or { unreadable: { file, code } } when the credentials path exists but cannot be read
+// (a folder, a locked ~/.heygen), so heygenAuthHeaders can say to fix that path: logging in again would fail there too.
+// Read without checking first, so the file cannot change between a check and the read.
+function resolveCredential() {
   const envKey = process.env.HEYGEN_API_KEY || process.env.HYPERFRAMES_API_KEY;
   if (envKey) return { headers: { "X-Api-Key": envKey } };
 
   const file = join(process.env.HEYGEN_CONFIG_DIR || join(homedir(), ".heygen"), "credentials");
-  // Callers only probe for a credential, so any path that cannot be read (missing, a folder, a locked ~/.heygen)
-  // is none. Read without checking first, so the file cannot change between a check and the read.
   let raw;
   try {
     raw = readFileSync(file, "utf8").trim();
-  } catch {
-    return null;
+  } catch (error) {
+    return error.code === "ENOENT" ? null : { unreadable: { file, code: error.code } };
   }
   if (!raw) return null;
   if (!raw.startsWith("{")) return { headers: { "X-Api-Key": raw } };
 
   // A malformed credentials file (partial write / wrong shape) must degrade to
-  // "no credential", not crash the engine at startup — this function never throws.
+  // "no credential", not crash the engine at startup.
   let cred;
   try {
     cred = JSON.parse(raw);
@@ -105,7 +111,7 @@ export function heygenAuthMethod() {
 
 // → auth headers object, or throw with a fix hint.
 export function heygenAuthHeaders() {
-  const cred = heygenCredential();
+  const cred = resolveCredential();
   if (cred?.headers) {
     // Only tag OAuth (Bearer) traffic as cli-source — the backend uses it to
     // grant the free allowance for OAuth requests and ignores it for API-key
@@ -115,6 +121,10 @@ export function heygenAuthHeaders() {
       ? { ...cred.headers, ...HEYGEN_CLI_SOURCE_HEADERS, ...HEYGEN_CLIENT_SOURCE_HEADERS }
       : { ...cred.headers, ...HEYGEN_CLIENT_SOURCE_HEADERS };
   }
+  if (cred?.unreadable)
+    throw new Error(
+      `HeyGen credentials at ${cred.unreadable.file} can't be read (${cred.unreadable.code}) — fix or remove that path, then run \`npx hyperframes auth login\``,
+    );
   if (cred?.expired)
     throw new Error(
       "HeyGen OAuth token expired — run `npx hyperframes auth refresh` (or `npx hyperframes auth login`)",

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

@@ -3,7 +3,12 @@ import assert from "node:assert/strict";
 import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { heygenAuthHeaders, heygenAuthMethod, loadEnvFromDir } from "./heygen.mjs";
+import {
+  heygenAuthHeaders,
+  heygenAuthMethod,
+  heygenCredential,
+  loadEnvFromDir,
+} from "./heygen.mjs";
 
 function withCleanHeygenEnv(fn) {
   const previousApiKey = process.env.HEYGEN_API_KEY;
@@ -141,3 +146,23 @@ test("heygenAuthMethod returns null when the credentials path is a symlink loop"
     }
   });
 });
+
+test("heygenAuthHeaders says to fix an unreadable credentials path, and to log in when there is none", () => {
+  withCleanHeygenEnv(() => {
+    const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
+    try {
+      process.env.HEYGEN_CONFIG_DIR = dir;
+      assert.throws(() => heygenAuthHeaders(), /no HeyGen credentials/);
+      mkdirSync(join(dir, "credentials"));
+      assert.equal(heygenCredential(), null);
+      assert.throws(
+        () => heygenAuthHeaders(),
+        (error) =>
+          error.message.includes(join(dir, "credentials")) &&
+          /fix or remove that path/.test(error.message),
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -45,10 +45,8 @@ export function pickProvider(userProvider) {
       throw new Error(
         "provider=gemini needs GEMINI_API_KEY or GOOGLE_API_KEY, or service-account credentials (GOOGLE_APPLICATION_CREDENTIALS or GCS_CREDS)",
       );
-    if (userProvider === "heygen" && !heygenAvailable())
-      throw new Error(
-        "provider=heygen but no HeyGen credentials (set $HEYGEN_API_KEY or run `npx hyperframes auth login`)",
-      );
+    // heygenAuthHeaders owns the reason and its fix: no credential, or a credentials path that cannot be read.
+    if (userProvider === "heygen" && !heygenAvailable()) heygenAuthHeaders();
     if (userProvider === "elevenlabs" && !process.env.ELEVENLABS_API_KEY)
       throw new Error("provider=elevenlabs but $ELEVENLABS_API_KEY is not set");
     return userProvider;

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

@@ -1,6 +1,14 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, readFileSync, writeFileSync, chmodSync, rmSync, existsSync } from "node:fs";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  writeFileSync,
+  chmodSync,
+  rmSync,
+  existsSync,
+} from "node:fs";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import {
@@ -9,6 +17,7 @@ import {
   synthesizeOne,
   synthesizeHeygen,
   synthResult,
+  pickProvider,
 } from "./tts.mjs";
 
 test("parseFfmpegDurationBanner reads ffmpeg's stderr Duration line", () => {
@@ -198,3 +207,24 @@ test(
     assert.ok(!(await kokoroArgv({})).includes("--speed"));
   },
 );
+
+test("pickProvider heygen with an unreadable credentials path says to fix that path", () => {
+  const saved = ["HEYGEN_API_KEY", "HYPERFRAMES_API_KEY", "HEYGEN_CONFIG_DIR"].map((k) => [
+    k,
+    process.env[k],
+  ]);
+  const dir = mkdtempSync(join(tmpdir(), "tts-cred-"));
+  try {
+    delete process.env.HEYGEN_API_KEY;
+    delete process.env.HYPERFRAMES_API_KEY;
+    process.env.HEYGEN_CONFIG_DIR = dir;
+    mkdirSync(join(dir, "credentials"));
+    assert.throws(() => pickProvider("heygen"), /fix or remove that path/);
+  } finally {
+    for (const [k, v] of saved) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/dist/skills/media-use/scripts/lib/manifest.d.mts

@@ -0,0 +1,19 @@
+export interface Reservation {
+  id: string;
+  localPath: string;
+  markerPath: string;
+  fullPath: string;
+}
+
+export function typeDirPath(projectDir: string, type: string): string;
+export function allocateId(
+  projectDir: string,
+  type: string,
+  ext: string,
+): Omit<Reservation, "fullPath">;
+export function withReservedFileSync<T>(
+  projectDir: string,
+  type: string,
+  ext: string,
+  populate: (reservation: Reservation) => T,
+): T;

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

@@ -10,6 +10,7 @@ import {
   rmSync,
   statSync,
 } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { basename, join } from "node:path";
 
 const MANIFEST_FILE = "manifest.jsonl";
@@ -202,12 +203,12 @@ function withLock(dir, fn) {
   }
 }
 
-// Atomically allocate the next free id for `type` AND reserve its file, so a
+// Atomically allocate the next free id for `type` AND reserve it on disk, so a
 // slow download/copy between allocation and appendRecord can't let a concurrent
 // caller grab the same id (the MU-23 clobber). Under the lock we take the max id
 // across BOTH the manifest and any already-reserved files in the type dir, then
-// O_EXCL-create an empty placeholder at the target path; freeze/copy overwrites
-// it. Returns { id, localPath }.
+// O_EXCL-create an empty marker under core's atomic temp name, which Studio's
+// project history skips. Returns { id, localPath, markerPath }.
 export function allocateId(projectDir, type, ext) {
   mkdirSync(mediaDir(projectDir), { recursive: true });
   const typeDir = typeDirPath(projectDir, type);
@@ -215,8 +216,10 @@ export function allocateId(projectDir, type, ext) {
   return withLock(mediaDir(projectDir), () => {
     const id = nextFreeId(projectDir, type);
     const localPath = `.media/${typeSubdir(type)}/${id}${ext}`;
-    writeFileSync(join(projectDir, localPath), "", { flag: "wx" }); // durable reservation
-    return { id, localPath };
+    // Same shape as core atomicTempPath: an empty file at the final name would be committed.
+    const markerPath = `${join(projectDir, localPath)}.hf${randomBytes(3).toString("hex")}.tmp`;
+    writeFileSync(markerPath, "", { flag: "wx" }); // durable reservation
+    return { id, localPath, markerPath };
   });
 }
 
@@ -242,22 +245,23 @@ function reservedFile(projectDir, type, ext) {
   return { ...allocation, fullPath: join(projectDir, allocation.localPath) };
 }
 
-function rollbackReservation(reservation) {
-  rmSync(reservation.fullPath, { force: true });
+function releaseReservation(reservation, committed) {
+  if (!committed) rmSync(reservation.fullPath, { force: true });
+  rmSync(reservation.markerPath, { force: true });
 }
 
 // A reservation is committed only when populate returns a non-null value.
 // Throwing/rejecting or returning null means no usable asset was produced, so
-// the placeholder must be released. Keeping this transaction beside allocateId
-// prevents individual provider/cache/LUT paths from forgetting the rollback.
+// the reservation and any partial asset are released. Keeping this transaction
+// beside allocateId prevents provider/cache/LUT paths from forgetting the rollback.
 export function withReservedFileSync(projectDir, type, ext, populate) {
   const reservation = reservedFile(projectDir, type, ext);
   try {
     const result = populate(reservation);
-    if (result == null) rollbackReservation(reservation);
+    releaseReservation(reservation, result != null);
     return result;
   } catch (error) {
-    rollbackReservation(reservation);
+    releaseReservation(reservation, false);
     throw error;
   }
 }
@@ -266,10 +270,10 @@ export async function withReservedFile(projectDir, type, ext, populate) {
   const reservation = reservedFile(projectDir, type, ext);
   try {
     const result = await populate(reservation);
-    if (result == null) rollbackReservation(reservation);
+    releaseReservation(reservation, result != null);
     return result;
   } catch (error) {
-    rollbackReservation(reservation);
+    releaseReservation(reservation, false);
     throw error;
   }
 }

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

@@ -100,7 +100,7 @@ function runTests() {
     setup();
     const allocated = allocateId(tmp, "lut", ".cube");
     assert.equal(allocated.localPath, ".media/luts/lut_001.cube");
-    assert.ok(existsSync(join(tmp, allocated.localPath)));
+    assert.ok(existsSync(allocated.markerPath));
     cleanup();
   });
 
@@ -157,7 +157,8 @@ function runTests() {
     setup();
     const a = allocateId(tmp, "bgm", ".wav");
     assert.equal(a.id, "bgm_001");
-    assert.ok(existsSync(join(tmp, a.localPath)), "placeholder reserved on disk");
+    assert.ok(existsSync(a.markerPath), "id reserved on disk");
+    assert.ok(!existsSync(join(tmp, a.localPath)), "no empty asset at the final name");
     // Second allocation BEFORE any manifest append (the download window) must not
     // hand back bgm_001 again, even with a different extension.
     const b = allocateId(tmp, "bgm", ".mp3");