fix(threads): worker threads must inherit the parent's in-process config overrides

[kriszyp]

What

The unitTests/apiTests suite's isolation (per-PID rootPath, per-process loopback address, port overrides) is applied with in-process env.setProperty() calls on the main thread. Worker threads spawned during the run booted with a fresh environmentManager/configUtils module state and re-read harper-config.yaml from disk, so a worker silently fell back to whatever was actually installed and bound its ports on the wildcard address — the suite only passed when the developer's ambient install happened to be shaped like CI's.

Two closely-related root causes, both closing the same invariant ("a worker's effective config equals its parent's effective config"):

1. Worker threads never received the parent's overrides at all. environmentManager.ts's flatConfigObj is module-scoped (each worker thread is its own V8 realm), populated once from disk. setProperty() only ever mutated the calling thread's own copy.

   • setProperty() now records every override into a canonical-name-keyed map (getConfigOverrides()), so different legacy aliases for the same param (e.g. SERVER_PORT_KEY / OPERATIONSAPI_NETWORK_PORT) collapse onto one last-write-wins entry instead of two independently-ordered ones.
   • manageThreads.js registers a configOverrides workerData provider via the existing registerWorkerDataProvider extension point, so every worker spawned from any thread — HTTP, job, or nested — inherits its parent's overrides.
   • initSync() replays inherited overrides once per thread, and replays the full accumulated override set again after any forced re-init (e.g. a component RESTART), since that re-reads the whole config from disk and would otherwise silently drop everything layered on top of it — on any thread, including main.

2. Even on the main thread, overrides never reached the nested config tree componentLoader.ts reads for built-in components. configUtils.ts keeps config in two representations: a flat map and a nested tree (configObj, via getConfigObj()). updateConfigObject() — what setProperty() calls — only ever wrote the flat map. componentLoader.ts's root-component load reads the nested tree directly and derives each built-in's network port/protocol from it (e.g. operationsApi.network.securePort decides whether operationsServer builds a TLS-only Fastify instance). So even with (1) fixed, a worker — or the main thread itself — whose ambient install had a non-null operationsApi.network.securePort still built a TLS-only listener, because componentLoader kept reading the stale on-disk value regardless of any override. Invisible on a CI-shaped install only because the on-disk value already happened to match what the harness wants.

   • updateConfigObject() now also mirrors into the nested tree, at the path implied by the flat key's underscore segments — with guards added over several review rounds: it never auto-vivifies configObj before a real config has ever loaded (would permanently short-circuit getConfigObj()'s lazy init), never clobbers an existing scalar shorthand (e.g. threads: 4) by descending through it, deletes rather than writes an undefined value (and doesn't auto-vivify ancestors just to immediately delete the leaf), and excludes params that live in BOOT_PROP_PARAMS rather than the actual YAML schema (settings_path is boot-props-file bookkeeping, not a real settings: config section — mirroring it naively would register a bogus settings component).

Three smaller, related fixes:

• setupTestApp.mjs nulled http.securePort when overriding http.port, but never did the same for operationsApi.network.securePort — an asymmetry that (combined with fix 2) left a stale TLS port in the effective config next to the plain-port override.
• mqtt-test.mjs's two mTLS tests selected the client certificate by the literal string 'localhost'. Switched to falling back through getThisNodeName() (the function the server itself uses to name its self-signed node cert) and then to any non-authority certificate, since getThisNodeName()'s own fallback chain can itself resolve differently between the install process and the test process on a hostname-null install (a fresh/non-replicated install has exactly one non-authority cert, so "any" is unambiguous here).
• dataLayer/harperBridge/lmdbBridge/lmdbUtility/initializePaths.js and utility/lmdb/environmentUtility.ts were calling env.setProperty() to cache values derived from config they'd just read (a schema path resolved from CLI args, a database's on-disk path) rather than genuine operator/harness overrides. Going through setProperty() made those derived values outlive a forced config reload and get shipped to every worker as if they were intentional overrides. Both now call configUtils.updateConfigObject() directly, which updates the same in-memory state without joining the override-tracking/propagation mechanism.

Production-path impact

config/configUtils.ts's updateConfigObject() change affects the same code path used at install time (utility/install/installer.ts) and any other env.setProperty() caller. This is a correctness fix within that path, not new behavior: it makes configObj/flatConfigObj consistent with each other, which is what setProperty()'s contract already implied. A worker that receives no overrides sees the new workerData provider return undefined and get skipped (per its existing "throws or returns non-cloneable → logged and skipped" contract) — production instances without in-process overrides see no behavior change.

Known limitation (out of scope for this PR)

Root components that use the newer Plugin API (handleApplication-based — MQTT, REST, fastifyRoutes, graphqlQuerying) read their config via OptionsWatcher, which re-parses harper-config.yaml off disk directly and never consults getConfigObj()/flatConfigObj at all. env.setProperty() overrides are invisible to that path. This PR's apitests verification (three different install shapes, including concurrent runs) didn't surface it because MQTT is still loaded through the older, componentLoader-driven path this PR does fix — but it's a real, pre-existing gap for any Plugin-API component, worth its own follow-up issue.

Testing

Verified against three different local installs (node ./dist/bin/harper.js install + isolated HOME, never the shared ambient install):

• Adversarial (operationsApi.network.port: null / securePort: 9925, http.port: null / securePort: 9926, node.hostname set to a non-'localhost' value — matches this issue's exact regression scenario): npm run test:unit:apitests 194 passing / 0 failing (was 181/10 on unpatched origin/main; 185/9 with only the worker-inheritance fix, before the nested-tree fix).
• CI-shaped (DEFAULTS_MODE=dev, NODE_HOSTNAME=localhost): 194/0, unaffected.
• Hostname-null (node.hostname unset entirely): 194/0 — this is what caught the mTLS cert-fallback issue above.
• npm run test:unit:main (4043 passing) and npm run test:unit:resources (1336 passing): unaffected, matches origin/main baseline (verified via a short-path throwaway worktree, since this repo's own worktree convention nests deep enough to independently trip two unrelated, pre-existing path-length issues — a domain-socket path limit and a Node module-sandbox check on a bare verification copy without its own node_modules — neither caused by this change).
• No more [http/N] ... EADDRINUSE ... :::1883 in apitests output; no server banner reports a Root Path outside the per-PID unitTests/envDir/<pid> directory.
• Two concurrent npm run test:unit:apitests runs get distinct loopback addresses with no EADDRINUSE and correct per-run Root Path banners — the wildcard-bind collision this PR targets is gone. A separate mqtt-test.mjs timing sensitivity was observed under 2x concurrent full-suite load on this shared dev machine; it isn't port/address-collision-shaped (addresses were confirmed distinct) and wasn't root-caused — flagged as a follow-up, not blocking.
• New unit tests for the override-tracking/replay mechanism (environmentManager.test.js) and the nested-mirror guards (configUtils.test.js).

This branch went through seven rounds of cross-model pre-push review (codex + gemini + grok + an internal Harper-domain pass) as fixes were made — see the commit messages for each round's findings and disposition.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces robust propagation and synchronization of in-process configuration overrides across main and worker threads, ensuring consistency and preventing configuration skew. It updates updateConfigObject to mirror overrides into the nested configuration tree, tracks overrides using canonical parameter names, and replays them upon worker thread initialization or forced configuration reloads. Additionally, direct configuration updates are used instead of setProperty for derived values to avoid unintended persistence. Feedback on the changes suggests using loose inequality (!= null) instead of strict inequality (!== undefined) when checking configObj to safely guard against both null and undefined values, adhering to the repository's style guide.

[claude]

Reviewed; no blockers found.