[PerryLink]

The up-front missing-env preflight scans a toolset's env values with raw os.Expand, while the runtime expands the same values through environment.ExpandAll (which normalizes ${env.X} to X first). For the canonical form — exactly what examples/mcp-definitions.yaml uses — the preflight records the literal name env.GITHUB_PERSONAL_ACCESS_TOKEN:

toolsets:
  - type: mcp
    ref: docker:github-official
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${env.GITHUB_PERSONAL_ACCESS_TOKEN}"

GatherEnvVarsForTools then returns ["env.GITHUB_PERSONAL_ACCESS_TOKEN"], and CheckRequiredEnvVars aborts the run even with GITHUB_PERSONAL_ACCESS_TOKEN set:

The following environment variables must be set:
 - env.GITHUB_PERSONAL_ACCESS_TOKEN
 - Shell environment: export env.GITHUB_PERSONAL_ACCESS_TOKEN=<value>

${env.X} is documented as the canonical syntax for every config field, including toolset env values (docs/configuration/overview/index.md), and environment.Refs is documented as the helper for exactly this kind of up-front check.

Change

Use environment.Refs(value) instead of raw os.Expand, so the preflight discovers the same names the runtime will expand.

Test

pkg/config/gather_mcp_env_test.go serves a static MCP catalog and checks three forms (${env.X}, ${X}, $X) with the variable set. On main the canonical subtest fails with the error above; with the change all three pass and the reported name is GITHUB_PERSONAL_ACCESS_TOKEN.

Validation

go test ./pkg/config/... ./pkg/teamloader -count=1      # ok
go vet ./pkg/config ; gofmt -l pkg/config               # clean

The full go test ./... has unrelated baseline failures in this environment (pkg/hooks hook commands exit 127 and pkg/runtime/TestDoCompactAfterHookFires); they reproduce without this change.

[aheritier]

👋 Some commits in this PR are not signed and verified by GitHub. Please sign your commits with a GPG or SSH key registered in your GitHub account, then force-push.

Commits that are not verified: def156a

See GitHub’s guide on signing commits for setup instructions. I’ve added status/needs-signed-commits; it will be removed automatically once every commit in this PR carries a valid GitHub-verified signature.