[Task]: Validate required environment variables at service startup (fail fast)

[grantfox-oss]

Every service (orchestrator, registry, each agent) reads configuration from process.env lazily, at the point of use. A missing or malformed variable therefore surfaces late — as a confusing runtime error deep inside a task (fetch to undefined, an Anthropic 401, a bad contract address) rather than at boot. With seven services deployed on Render and a large .env.example, a misconfigured deploy should fail immediately with a clear message naming the missing keys, not limp along and break on the first task.

Goal

A small, dependency-light config helper in packages/common/src, exported from the package index, that each service calls once in its entrypoint before starting its HTTP server. It should validate presence (and, ideally, basic shape) of the vars that service needs, and exit non-zero with a message listing everything that's wrong — all missing keys at once, not one at a time.

Requirements & constraints

• Presence checks at minimum; optional typed helpers for shape (URL, number, Stellar address) are a plus.
• Each service owns its own required-key list (e.g. the orchestrator needs REGISTRY_URL, VAULT_CONTRACT_ID, and ANTHROPIC_API_KEY — except when LLM_PROVIDER=mock, which must not require the API key; agents need REGISTRY_URL and their wallet vars).
• The required-key lists must be reconciled against .env.example so docs and enforcement stay in sync.
• Treat empty/whitespace-only values as missing.

Edge cases to consider

• The LLM_PROVIDER=mock path must boot with no ANTHROPIC_API_KEY.
• A partially-configured deploy (three vars missing) reports all three in one message.
• Vars that are legitimately optional must not be flagged.

Acceptance criteria

• Validation helper added to packages/common/src and exported from the index
• Orchestrator, registry, and each agent validate their required vars at startup and exit non-zero with a clear, aggregated message on failure
• LLM_PROVIDER=mock boots without ANTHROPIC_API_KEY
• Empty/whitespace values treated as missing
• Required-key lists reconciled with .env.example
• Vitest coverage: missing, present, whitespace-only, aggregated multi-missing, mock exception
• npm test passes

Relevant files

• new packages/common/src/env.ts (+ packages/common/src/index.ts)
• packages/orchestrator/src/server.ts, packages/registry/src/server.ts, each packages/agents/*/src/server.ts
• .env.example

Notes for contributors

If you'd like to work on this, comment below so we can assign it to you.
Questions welcome — see CONTRIBUTING.md for setup
and workflow.

[temisan0x]

Good day team, please i’d like to take on this issue

[blvckmamba81-sketch]

Hi! I'd like to take on this issue. I have experience improving application startup and configuration validation. I'll implement fail-fast validation for all required environment variables, provide clear error messages for missing or invalid values, and add tests to ensure the service exits cleanly when configuration is incomplete.

[grantfox-oss]

🦊 GrantFox — @temisan0x has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #88)
2. Your PR will be reviewed by the clevercon-protocol maintainers

Good luck! Track your progress on GrantFox.