Fail soft on operations API domain socket bind failure; warn on path-length overflow

[kriszyp]

What / why

A Unix domain socket path over ~107 bytes (Linux) / ~103 bytes (macOS) fails at listen() time with EINVAL. server/threads/threadServer.js's listenOnPorts() wrapped every listener — the operations API's domain socket and its TCP port alike — in one Promise.all(), so a single EINVAL rejected the whole batch and propagated out of startHTTPThreads(), which bin/run.ts's main() catches by calling process.exit(1) — killing the entire Harper process over what should be a non-fatal loss of a convenience mirror.

A long rootPath (e.g. any .claude/worktrees/<name> checkout — this fix was developed in one) is enough on its own to trigger this with the operations API's default relative domain socket name (operations-server), with nothing in the default output explaining why.

Changes

• server/threads/threadServer.js: a domain socket listen failure now logs and resolves instead of rejecting, in both the Node and Bun listen loops, so the rest of the batch (TCP ports, other domain sockets) is unaffected.
• validation/configValidator.ts: adds getDomainSocketPathLengthWarning, which resolves operationsApi.network.domainSocket against rootPath and flags a byte length past the platform's sun_path limit. It's a plain function rather than a Joi schema rule, because Joi skips a field's own .custom() whenever that field's value came from .default() — exactly the common case here (domain socket left unset, only rootPath is long).
• config/configUtils.ts: calls the warning check after config validation and logs (non-blocking) — a lost domain socket shouldn't refuse to start Harper the way a real config error does; the TCP port is unaffected either way.

Test notes

• unitTests/server/threads/threadServerListenOnPorts.test.js (new): confirms listenOnPorts() resolves rather than rejects when a domain socket listen fails, and that a sibling TCP listener in the same batch still comes up. Verified these fail against the pre-fix code (rejected with the simulated EINVAL).
• unitTests/validation/configValidator.test.js: unit tests for getDomainSocketPathLengthWarning covering relative/absolute paths, the disabled (false) case, and the exact byte boundary.
• unitTests/config/configUtils.test.js: confirms validateConfig logs a warning (not a thrown error) when the resolved domain socket path is too long.
• Ran test:unit:config, test:unit:validation-equivalent, and the affected unitTests/server/** files locally — all green, no regressions.

Risks / open questions

• The path-length check is a warning, not a hard validation error, by design (see rationale above) — flagging in case reviewers feel a long-path config should instead fail config validation outright.
• Didn't touch server/operationsServer.ts, which the originating finding cited — that file's try/catch around serverRegistration.http(...) never actually reaches the failing listen() call (that happens later, on the main thread, in threadServer.js's listenOnPorts()), so no change was needed there.

Generated with Claude Code (Sonnet 5).

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a fail-soft mechanism for Unix domain socket binding errors during startup, preventing startup abortion when a domain socket path exceeds the platform's limit (103 bytes on macOS, 107 bytes on Linux). It adds path length validation warnings in configUtils.ts and configValidator.ts, along with corresponding unit tests. The reviewer suggests updating getDomainSocketPathLengthWarning to accept an optional platform parameter to facilitate robust, platform-independent unit testing of the path resolution logic on any CI host.

[claude]

Reviewed; no blockers found.