Authored by Claude Opus 4.7 (Claude Code). Session ba55de70-c601-448e-9eb4-9c214be1d9c6.

FAIR-band: operator-directed audit + execution at 2026-05-27T15:50Z. Operator anchor: "are you still aware of our config and env var patterns? this one did not get created inside this session. however, it is not the only spot. the orchestrator needs a review." Then at 16:21Z: "do we REALLY need 3-4 PRs, or can we do it with 1-2? go!" — committing to single comprehensive PR.

Closes #12097

Audit + single-PR consolidation of orchestrator config/env-pattern violations predating the operator-stated NO HIDDEN DEFAULT VALUE FALLBACKS IN CODE contract (banked at feedback_no_hidden_default_fallbacks.md; PR #12061 cycle-4 anchor). envBindings.orchestrator.* now owns env-vs-config precedence at config-load time for 29 keys previously resolved via per-access getters in Orchestrator.mjs; the orchestrator + sibling services read AiConfig.X.Y directly.

Evidence: L2 (npm run test-unit -- --grep "Orchestrator|PrimaryRepoSync|SwarmHeartbeat|config.template" → 384/386 pass locally; the 2 remaining DreamService failures are PRE-EXISTING — verified via git stash baseline test on the same grep, identical failures both pre- and post-refactor; unrelated to this PR's scope). L4 deferred to the post-merge runtime check that the orchestrator daemon boot reads the env-applied values via envBindings.

Deltas from ticket (if any)

Two intentional preservations vs the ticket's "delete all resolvers" framing:

1. resolveDeploymentEnabled + resolveCloudOnlyEnabled kept — they encode the documented null-means-deployment-default sentinel on localOnly/cloudOnly config slots. The helpers don't read env (env is handled by envBindings); they pure-derive from AiConfig. The operator-visible null semantic on those slots is preserved as part of the deliberate config contract. The getters that previously combined env-read + helper now just call the helper.
2. 2 getters stayed in Orchestrator.mjs:
   • swarmHeartbeatIdentity reads NEO_AGENT_IDENTITY directly — this is a top-level identity var, not orchestrator-scoped; moving it into orchestrator envBindings would be wrong shape. Lives at the higher-tier identity boundary.
   • swarmHeartbeatExplicitTargets does consumer-side comma-separated string → array splitting. The raw string lands via the new AiConfig.orchestrator.swarmHeartbeat.targets envBinding; the getter just splits + trims. Array-shape parsing is consumer-side concern, not config-shape.

What changes

ai/config.template.mjs (+50 LOC)

• defaultConfig gains wakeDaemonHeartbeatAlivePath (neoRootDir-rooted default).
• envBindings.orchestrator.* gains 26 new entries: intervals (9), tenantRepoSync.{sweep,jitter}, swarmHeartbeat.{targetSource,targets}, localOnly.* (6 enable flags), cloudOnly.tenantRepoSyncEnabled, mlx.{enabled,model,port}, lms.{enabled,model,port}, devSyncRoots.
• envBindings gains wakeDaemonHeartbeatAlivePath: 'NEO_HEARTBEAT_ALIVE_PATH'.

ai/daemons/orchestrator/Orchestrator.mjs (+39 / -104)

• DELETE 27 of 29 env-reading getters; replacements read AiConfig.orchestrator.X.Y directly.
• DELETE 2 export functions (resolvePrimaryDevSyncRootsConfig + resolvePrimaryDevSyncRootsSource) — env precedence is the envBindings tier's responsibility.
• DELETE import of DEV_SYNC_ROOTS_CONFIG_KEY + DEV_SYNC_ROOTS_ENV_VAR from PrimaryRepoSyncService (no longer needed at this layer).
• this.primaryDevSyncRootsConfig instance field defaults to AiConfig.orchestrator.devSyncRoots when no explicit constructor value is passed.
• Dream-task callback delegates devSyncRootsConfig: this.primaryDevSyncRootsConfig directly (no resolver call, no env probe).

ai/daemons/orchestrator/services/PrimaryRepoSyncService.mjs (+5 / -14)

• DELETE devSyncRootsConfig = process.env[DEV_SYNC_ROOTS_ENV_VAR] default-parameter env reads from runTask + syncPrimaryDev.
• DELETE devSyncRootsSource parameter — syncPrimaryDev hardcodes the canonical NEO_ORCHESTRATOR_DEV_SYNC_ROOTS label for error reporting since envBindings now owns precedence.
• DELETE export const DEV_SYNC_ROOTS_CONFIG_KEY (last consumer was a now-deleted test assertion).

ai/daemons/orchestrator/services/SwarmHeartbeatService.mjs (+1 / -2)

• ADD import AiConfig from '../../../config.mjs'.
• heartbeatAlivePath() now reads AiConfig.wakeDaemonHeartbeatAlivePath instead of process.env.NEO_HEARTBEAT_ALIVE_PATH || path.resolve(__dirname, '...').

Tests (4 files updated)

• Orchestrator.spec.mjs: 'passes local dev-sync roots to primary-dev-sync while env keeps precedence' → 'delegates the configured dev-sync roots to PrimaryRepoSyncService via options.devSyncRootsConfig'. Drops env-precedence assertions (now envBindings tier's responsibility) + drops devSyncRootsSource assertion (param removed).
• Orchestrator.invariants.spec.mjs: describe block renamed from 'Orchestrator config precedence' to 'Orchestrator config getters delegate to AiConfig (envBindings is the env-precedence SSOT)'. Tests rewritten to assert getter→AiConfig delegation rather than env-precedence. Deployment-default null-fallthrough invariants preserved (they're the resolver helpers' contract).
• PrimaryRepoSyncService.spec.mjs: test name + error message expectation aligned to the new DEV_SYNC_ROOTS_ENV_VAR-canonical source label.
• SwarmHeartbeatService.spec.mjs: heartbeatAlivePath test mutates AiConfig.wakeDaemonHeartbeatAlivePath instead of process.env.NEO_HEARTBEAT_ALIVE_PATH.

Test Evidence

• npm run test-unit -- --grep "Orchestrator|PrimaryRepoSync|SwarmHeartbeat|config.template" → 384/386 pass locally. 2 failures (DreamService.spec synthesizeGoldenPath + should retry extraction on malformed JSON payload) are PRE-EXISTING — confirmed via git stash; npm run test-unit -- --grep "DreamService.*should retry extraction"; git stash pop showing the same failure on pre-refactor baseline. Out of scope for this PR.
• §15.6 diagnostic on added lines: zero new violations (the one (#12019) match is a test('...') label, which is the documented §15.6 exception per feedback_jsdoc_archaeology_self_audit).
• Capability-framing audit: zero downstream-deployment-partner mentions.
• Pre-existing (#11834 AC2) describe-block label updated to remove the ticket reference per §15.6 (renamed to plain prose).

Post-Merge Validation

• Boot the orchestrator daemon (npm run ai:orchestrator or equivalent) with NEO_ORCHESTRATOR_POLL_INTERVAL_MS=5000 set in the env and confirm the running orchestrator's pollIntervalMs matches the env value (verifies envBindings.orchestrator.intervals.pollMs is correctly applied at config-load time).
• Same probe with NEO_HEARTBEAT_ALIVE_PATH=/tmp/heartbeat.alive and confirm the SwarmHeartbeatService's next pulse touches the override path.
• Confirm Orchestrator.mjs line count net-decreased relative to dev (cycle-1 deletes 27 getters + 2 resolver functions; thinning is part of the operator-flagged restoration arc).

Commits

• 08805fa50 — refactor(orchestrator): collapse env-or-config getters into envBindings; drop in-code env reads + resolver bypasses (#12097)

Evolution

The four anti-pattern clusters (env-reading getters, resolver functions, direct process.env || hardcoded, default-parameter env reads) all collapse under one fix shape because they all violate the same architectural mandate: env-vs-config precedence belongs to the envBindings tier, not to runtime code. Each cluster bypassed envBindings in a different way; the single PR re-routes all four through the canonical surface so future drift is caught at the envBindings layer instead of leaking into 30+ places. Operator's "1-2 PRs, go!" framing made the single-PR consolidation the explicit shape — the alternative would have been 3-4 narrow PRs that share the same architectural fix and force three review cycles for one architectural correction.