fix: write Harper config files atomically

[Devin-Holland]

Summary

Replaces direct fs.writeFileSync in config/configUtils.js with a temp-file + fs.renameSync helper so concurrent readers never observe a truncated or empty file during a rewrite.

Why

fs.writeFileSync opens the target with O_TRUNC and then writes — between those two calls the file is zero-length. If a reader reads in that window it gets an empty buffer; YAML.parseDocument('') returns a document with no top-level keys, and downstream configValidator then throws rootPath config parameter is undefined and the worker calls process.exit(1).

This was hit in the field on a six-node cluster: one node's clone wedged with the worker logs:

[http/4] [warn]: Cannot apply runtime env config: rootPath not found in config
[http/4] [error]: Error initializing environment manager
[http/4] [error]: rootPath config parameter is undefined

The race window is opened by cloneNode/cloneNode.ts calling cloneConfig() (which rewrites the config file via createConfigFile) after main() has already started spawning HTTP workers — workers running env.initSync() can land their readFileSync exactly during the truncate-to-write interval. Since process.exit from a worker only kills that worker (not the parent), the clone process continued running but in a wedged state with no exit code, so the container never restarted.

What changed

• New internal helper atomicWriteFile(filePath, content) in config/configUtils.js that writes to <filePath>.<pid>.<timestamp>.tmp and fs.renameSyncs over the target.
• Replaced six writers: createConfigFile, checkForUpdatedConfig, updateConfigValue, applyRuntimeEnvVarConfig, addConfig, deleteConfigFromFile. The race exists for any concurrent reader, not only clone.
• Test coverage: 4 new unit tests for the helper itself; updated the existing applyRuntimeEnvVarConfig write test to verify the temp+rename pair.

Areas to look at

• Helper placement and signature. Single internal function in configUtils.js, not exported. If you'd prefer it lives in a shared utility instead, easy to move.
• Temp file naming (<filePath>.<pid>.<Date.now()>.tmp). Same directory as target so the rename is atomic on the same filesystem. Pid+timestamp avoids collisions across processes/threads. Worth confirming this is acceptable on the deployment filesystems we care about.
• The addConfig async → sync conversion. Line 966 was await fs.writeFile(...); now uses the sync helper. addConfig is in an async function but called rarely (config-add ops API), so blocking briefly is fine. Flag if you'd rather an async variant.
• Out of scope, intentionally. Did NOT touch cloneNode.ts ordering or environmentManager.initSync's process.exit. The atomic write closes the actual race; reordering clone vs main() is a structural change with broader risk surface, and process.exit from a worker is a separate footgun worth its own PR.

Test plan

• npm run test:unit:config passes locally (51 passing)
• Manually verify a fresh clone on a multi-node cluster no longer wedges

[claude]

Reviewed; no blockers found.

[cb1kenobi]

This is a great trick. I used it like 12 years ago as it was the only way to atomically write a file. Nice.

[cb1kenobi]

If you put the encoding here, then you don't need the String() calls all over the place.

Suggested change

	fs.writeFileSync(tempPath, content);
	fs.writeFileSync(tempPath, content, 'utf-8');

[kriszyp]

This should protect against partial files, but if there is still a race condition of writing to a config file at the same time you are hoping workers read the write, that still... a race condition.

[cb1kenobi]

This should protect against partial files, but if there is still a race condition of writing to a config file at the same time you are hoping workers read the write, that still... a race condition.

Are you suggesting ${filePath}.${process.pid}.${Date.now()}.tmp may conflict? I've seen that happen and why I now use randomBytes(8).toString('hex') for temp filenames.

[kriszyp]

This should protect against partial files, but if there is still a race condition of writing to a config file at the same time you are hoping workers read the write, that still... a race condition.

Are you suggesting ${filePath}.${process.pid}.${Date.now()}.tmp may conflict? I've seen that happen and why I now use randomBytes(8).toString('hex') for temp filenames.

No, I meant that if the main thread needs to write something to harper-config.yaml that the child thread needs to read, using an atomic write just prevents a partial file, but if there was a race condition it still might not see whatever the main thread is concurrently working to write that it wants to communicate. I don't know what that is though.