Env-primitive deduplication: EnvConfig.mjs deletion + MCP migrations + Orchestrator scoped-binding

Authored by: [Claude Opus 4.7] (Claude Code)

Parent Epic: #11871 — Sub 1 of the env-primitive deduplication + shared MCP stderr logger Epic graduated from Discussion #11869 cycle-2.2.

Decision Record impact: none directly; aligned with ADR 0014 cloud deployment topology (preserves the existing per-deployment composability model; no central NEO_* catalog).

Context

Discussion #11869 cycle-2.2 graduated this Sub as the env-primitive consolidation half of Epic #11871. Three coexisting env-binding mechanisms surfaced this session — EnvConfig.mjs (Tier-2 MCP shared, strict parseBool) + Neo.util.Env (Tier-1, permissive parseBool, created via task #22) + ai/config/env.mjs (Sub 14 / PR #11868 introduced as 3rd mechanism). Plus runtime-mutable global state in ai/config/env.mjs (Orchestrator mutates env.NEO_ORCHESTRATOR_SWARM_HEARTBEAT_ENABLED = false on swarm-heartbeat init failure — env-abuse for runtime state). Direct cutover, no shim (v13 unreleased per operator).

The Problem

Per the cycle-2.2 narrow scope:

Consumer ledger (per @neo-gpt cycle-2 STEP_BACK correction):

• Direct EnvConfig.mjs imports: knowledge-base, memory-core, neural-link, gitlab-workflow config.templates (4 files)
• Indirect via BaseConfig.mjs: github-workflow (transitive coverage)
• BaseConfig.mjs itself imports EnvConfig.mjs
• initServerConfigs.spec.mjs asserts old EnvConfig import strings — must update

The Architectural Reality

Current orchestrator getter chain is already pure 2-layer per operator direction ("env var if set wins, otherwise aiConfig"):

get swarmHeartbeatEnabled() {
    return env.NEO_ORCHESTRATOR_SWARM_HEARTBEAT_ENABLED ?? resolveDeploymentEnabled('swarmHeartbeatEnabled');
}

After ai/config/env.mjs deletion, getter shorthand must still mean a PARSED env layer (per @neo-gpt cycle-2.2 implementation clarification — raw process.env.X strings would reintroduce the boolean bug OQ1 fixes):

get swarmHeartbeatEnabled() {
    return Env.parseBool(process.env.NEO_ORCHESTRATOR_SWARM_HEARTBEAT_ENABLED, 'NEO_ORCHESTRATOR_SWARM_HEARTBEAT_ENABLED')
        ?? resolveDeploymentEnabled('swarmHeartbeatEnabled');
}

Runtime auto-disable on swarm-heartbeat init failure (currently env.NEO_X = false mutation) refactors to daemon-local instance field on the service (e.g., this.swarmHeartbeatService.initFailed = true), checked at poll() before pulse(). NOT a getter-chain layer. NOT env mutation. NOT AiConfig mutation. Preserves the fail-safe invariant (init failure disables lane regardless of env override) without re-introducing the env-mutation anti-pattern.

dotenv/config placement moves from deleted ai/config/env.mjs to orchestrator entrypoint (ai/scripts/orchestrator-daemon.mjs) deliberately. Cloud deployment doesn't need it (env-only via compose); local dev needs it for .env file load.

The Fix

1. Delete ai/mcp/server/shared/helpers/EnvConfig.mjs
2. Migrate 4 MCP server config.templates (knowledge-base, memory-core, neural-link, gitlab-workflow) + BaseConfig.mjs to Neo.util.Env.applyEnvBindings. Identical envBindings dotted-path shape; only the helper-module import changes
3. Update initServerConfigs.spec.mjs assertions for new import strings
4. Reconcile parseBool to permissive semantic (true/yes/on/1 / false/no/off/0); add boolean-binding migration tests proving operator inputs valid under either old strict OR new permissive evaluate identically
5. Delete ai/config/env.mjs + its spec
6. Orchestrator getters become Env.parseBool(process.env.NEO_X, 'NEO_X') ?? resolveDeploymentEnabled(key) for booleans / Env.parseNumber(...) ?? AiConfig.orchestrator.intervals.X for intervals. Pure 2-layer chain; parsed env layer inlined
7. Orchestrator runtime auto-disable: refactor env.NEO_ORCHESTRATOR_SWARM_HEARTBEAT_ENABLED = false to this.swarmHeartbeatService.initFailed = true (daemon-local instance field), poll() swarm-heartbeat lane checks the field before calling pulse()
8. Move dotenv/config import to ai/scripts/orchestrator-daemon.mjs entrypoint
9. Update Orchestrator.spec.mjs + MaintenanceBackpressureService.spec.mjs etc. for the new orchestrator import surface

Acceptance Criteria

1. EnvConfig.mjs deleted; all 4 direct importers + BaseConfig.mjs migrated to Neo.util.Env.applyEnvBindings. Grep-clean: zero EnvConfig.mjs references in ai/
2. Neo.util.Env.parseBool is the single canonical bool parser (permissive tokens); migration tests cover dual-semantic compatibility for operator inputs
3. ai/config/env.mjs + its spec deleted
4. Orchestrator boolean getters become Env.parseBool(process.env.NEO_X, 'NEO_X') ?? resolveDeploymentEnabled(key); interval getters become Env.parseNumber(process.env.NEO_X, 'NEO_X') ?? AiConfig.orchestrator.intervals.X. Pure 2-layer chain. No runtime mutation of either layer
5. Swarm-heartbeat init-failure auto-disable refactored to daemon-local instance field on the service; poll() checks field before pulse(). Fail-safe invariant preserved (init failure disables lane regardless of operator env override)
6. dotenv/config moved to ai/scripts/orchestrator-daemon.mjs entrypoint
7. initServerConfigs.spec.mjs assertions updated for new import strings
8. All existing tests pass; no process.env.NEO_* direct (unparsed) reads in migrated consumers
9. Orchestrator.spec.mjs + MaintenanceBackpressureService.spec.mjs + Env.spec.mjs all green

Out of Scope

(Each merits separate Discussion if later V-B-A surfaces real drift)

• Top-level + per-server config merge contract (cycle-1 rejected as framed)
• Two-file .template → .mjs pattern at ai/ root
• bootstrapWorktree.mjs scope extension to ai/config.template.mjs
• npx neo-app workspaces JSON config path
• Bare process.env.X || default reads in bridge/daemon.mjs / KbAlertingService.mjs / TaskDefinitions.mjs
• SwarmHeartbeatService core.Base contract cleanup (separate ticket — overlapping env-var reads will harmonize naturally during impl)
• Shared MCP stderr logger primitive (Epic #11871 Sub 2 — separate ticket)

Avoided Traps

• Re-introducing the 3rd-mechanism ai/config/env.mjs shape — explicitly resolved by AC 3
• Strict parseBool retention — resolved by AC 2 permissive cutover (zero docs/skills pin strict per cycle-2 V-B-A)
• Daemon-local field layered into getter chain — operator rejected ("env var if set wins, otherwise aiConfig"); resolved by AC 5 (field is poll-time check, NOT a chain layer)
• Mutating AiConfig.localOnly for runtime auto-disable — breaks fail-safe invariant if env override present; resolved by AC 5 daemon-local-field path
• Raw process.env.X reads post-deletion — would reintroduce boolean bug OQ1 fixes; resolved by AC 4 parsed-env-layer requirement
• Central NEO_* catalog every service imports — negative boundary; resolved by AC 1 per-server scoping preservation

Contract Ledger

Per pr-review §5.4 audit requirement for PRs touching public/consumed surfaces. Lane A introduces the canonical Neo.util.Env primitive consumed by MCP server config templates + the Orchestrator daemon getters. Contract surface enumerated below:

No behavioral change at the consumer level: every env var (NEO_ORCHESTRATOR_KB_SYNC_ENABLED, NEO_AGENT_IDENTITY, etc.) still maps to the same decoded value with the same fallback semantics; only the import path + parser invocation shape changed. The semantic-shift on parseBool (parseEnabledFlag permissive tokens → unified Env.parseBool permissive tokens) is internal-only since both decoders accepted identical token sets pre-cutover.

Authority

Discussion #11869 cycle-2.2 graduation (anthropic AUTHOR_SIGNAL + openai GRADUATION_APPROVED by @neo-gpt @ DC_kwDODSospM4BA_W0) + operator GO 2026-05-24 + nightshift lane-claim 2026-05-24.