media-use prefs.mjs: parallel record calls fail with ENOENT on a shared preferences.json.tmp and lose keys #5333

Describe the bug

writePrefsFile() in skills/media-use/scripts/lib/prefs-store.mjs writes atomically, through a temporary file and then a rename. But the temporary name is fixed:

const tmp = `${path}.tmp`;
writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`);
renameSync(tmp, path);

When two prefs.mjs record processes run at the same time, they share preferences.json.tmp. The first rename moves the file away, and the second rename fails with ENOENT.

There is a second, related problem. record reads the whole file, changes one key and writes the whole file back, so concurrent calls also overwrite each other's keys. A call that exits 0 can still lose its value.

This is easy to hit from the documented workflow. faceless-explainer Step 0 asks the agent to record each preference-backed answer with prefs.mjs record, and an agent following it ran those calls in parallel (one per key).

Steps to reproduce

MEDIA=<path to skills/media-use>
mkdir /tmp/prefs-repro && cd /tmp/prefs-repro && echo '{}' > hyperframes.json
export HYPERFRAMES_MEDIA_HOME=/tmp/prefs-repro/home   # keeps the real ~/.media out of the test
node $MEDIA/scripts/prefs.mjs record --hyperframes . --key destination --value youtube-shorts &
node $MEDIA/scripts/prefs.mjs record --hyperframes . --key aspect --value 1080x1920 &
node $MEDIA/scripts/prefs.mjs record --hyperframes . --key language --value en &
node $MEDIA/scripts/prefs.mjs record --hyperframes . --key flow --value automation &
wait; cat .media/preferences.json

Expected behavior

All four record calls succeed, and .media/preferences.json contains all four keys.

Actual behavior

Over 3 runs, 2–3 of the 4 calls exited with:

ENOENT: no such file or directory, rename '<project>/.media/preferences.json.tmp' -> '<project>/.media/preferences.json'

Only 0–2 of the 4 keys were kept (run 1: none; run 2: destination; run 3: flow, aspect).

Suggested fix

1. Use a unique temporary name, as scripts/lib/telemetry.mjs already does: ${path}.${process.pid}.tmp. manifest.mjs uses random bytes for the same purpose. This removes the ENOENT.
2. To also stop lost updates, serialise the read-modify-write in recordPreference(). For example, take a lock with mkdirSync(${path}.lock) and a short retry loop, then re-read the file under the lock before writing.

Alternatively, or as well, Step 0 of the workflow skills could say that record calls must run one after another.

I'm happy to open a PR for (1) and (2) if that would help.

Environment

• hyperframes CLI 0.8.140
• Skills from heygen-com/hyperframes; prefs-store.mjs is unchanged on main as of 2026-10-09
• macOS 15 (Darwin 24.6), Node 24.14.1