[codex] Structure server settings failures

[juliusmarminge]

Summary

• replace free-form server settings error details with a typed operation and optional provider/environment context
• preserve the exact underlying cause at every settings failure boundary and include it in fallback diagnostics
• remove the constructor-only settings error wrapper and construct errors where context is known

Validation

• vp test apps/server/src/serverSettings.test.ts
• vp check
• vp run typecheck

---

Note

Medium Risk
The error shape is a contract change (removes detail) and paths that materialize provider secrets now expose structured failure context; impact is limited to server settings and its callers.

Overview
ServerSettingsError is now structured instead of carrying a free-form detail string. The contracts layer adds a ServerSettingsOperation enum and optional providerInstanceId / environmentVariable fields; cause is required and kept as the original failure. User-facing message is built from the operation and context, not from nested error text.

Server settings code constructs these errors at each boundary (file I/O, normalization, secret read/write/remove, directory prep) with the matching operation label. Startup and change-stream warnings log operation, provider/env context, and cause instead of detail. Invalid settings.json parse warnings also attach the decode cause.

A new test asserts that a failed provider environment secret read returns read-secret context, preserves the exact underlying SecretStoreReadError, and does not embed that cause’s message in ServerSettingsError.message.

^{Reviewed by Cursor Bugbot for commit b38c1ad. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Structure ServerSettingsError with typed operations and contextual fields

• Replaces the generic detail string on ServerSettingsError with a typed operation field (e.g. read-secret, write-file, normalize) and optional providerInstanceId and environmentVariable fields.
• Adds cause as a required field on ServerSettingsError; the error message no longer embeds the cause message.
• Updates all error construction sites in serverSettings.ts and serverRuntimeStartup.ts to use the new shape.
• Adds a test in serverSettings.test.ts that verifies context propagation when a secret read fails.
• Behavioral Change: ServerSettingsError message format changes and no longer includes the underlying cause message; callers that parse or display this message will see different output.

^{Macroscope summarized b38c1ad.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 94731a48-f4f0-4158-9eeb-f81f3599ed46

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structure-server-settings-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling to use structured fields instead of free-form detail strings, improving error machine-readability. Changes are self-contained to error construction and formatting, with no impact on core business logic.

^{You can customize Macroscope's approvability policy. Learn more.}