[settings-naming] cli: normalize env vars — TRACEBLOC_ENV alias + TRACEBLOC_ prefix

[aptracebloc]

Normalizes this repo's owned stage-selecting environment variable toward the RFC-0076 canon, alias-first — read new-or-old, never break an existing deployment. TRACEBLOC_ENV becomes the canonical name; the legacy name is read as a fallback with remove_by: 2026-12-31.

Old → new env-var map

legacy (still read, remove_by: 2026-12-31)	canonical (preferred)	where
$CLIENT_ENV (process env)	$TRACEBLOC_ENV	api.ResolveEnv — the CLI's own stage read (--env flag still wins over both)
CLIENT_ENV (jobs-manager Deployment spec)	TRACEBLOC_ENV	doctor egress probe — the cluster's stage, read off the chart-written container env (consumer-side alias)

Value semantics are unchanged: dev/stg/prod resolution is identical, and the stg-vs-staging value spelling is a separate later step per the issue.

Scope notes

• Stage var (task 1) + TRACEBLOC_ prefix (B5, task 2) collapse to the single owned unprefixed var here — CLIENT_ENV. Every other owned var already carries the prefix (TRACEBLOC_CONFIG_DIR, TRACEBLOC_LOG_LEVEL, TRACEBLOC_INSTALLER, TRACEBLOC_ALLOW_UNVERIFIED, TRACEBLOC_NO_TELEMETRY, …).
• Config keys (task 3): none present to rename — there is no REGISTRY_URL/SKIP_TELEMETRY/TRACEBLOC_SKIP_* in this repo, and the one boolean gate (TRACEBLOC_ALLOW_UNVERIFIED) is already B5-compliant. Nothing deferred.
• Docs (task 4): no CLAUDE.md/README/BUGBOT.md/runbook names the old var. The user-facing surface that named it — the login / auth status --check --env help and the unknown-env error — now names $TRACEBLOC_ENV (legacy noted); goldens regenerated.
• Left as third-party (unchanged): MYSQL_* entrypoint contract, AWS_*/AZURE_*/KUBECONFIG, and the terminal/framework standards NO_COLOR/TERM/COLORTERM/COLORFGBG/CI/DO_NOT_TRACK/HTTP(S)_PROXY.

Guard + hermeticity

• The env-resolution meta-guard (TestNoNewEnvironmentResolutionSiteAppears) now registers TRACEBLOC_ENV as a needle, so a new read of either name lands in the sanctioned allowlist. Both touched files were already sanctioned sites.
• Because the canonical name now out-ranks CLIENT_ENV, a test that pinned the ambient stage via only one name would be non-hermetic under an ambient value of the other (plausible on settings-naming work). A package TestMain clears both stage vars at process start — verified: the cli/api/doctor suites pass with TRACEBLOC_ENV=dev CLIENT_ENV=dev in the environment.
• doctor's literal keys are pinned in lock-step with the api consts by a compile-checked test assertion.

VERSION bump

Yes — 0.10.24 → 0.10.25. The env reads live under internal/*, which the version-bump-gate treats as a published/packaged path.

Closes #656
Part of tracebloc/backend#3391

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes which backend URL the CLI and doctor probes target when both stage env vars are set differently; backward-compatible if only CLIENT_ENV is set, but mis-set TRACEBLOC_ENV could redirect sessions or egress checks unexpectedly.

Overview
Introduces RFC-0076 stage naming: $TRACEBLOC_ENV is canonical; $CLIENT_ENV remains a fallback until 2026-12-31. Resolution order is unchanged in spirit — --env, then env vars, then prod — but the env-var step now reads TRACEBLOC_ENV first, then CLIENT_ENV.

api.ResolveEnv centralizes that in stageFromEnv() (the only process-env reader for stage in the module). login / auth status --check help and unknown-env errors document the new default chain; goldens updated.

doctor backend egress uses the same alias-first rule for the cluster stage on the jobs-manager Deployment (TRACEBLOC_ENV, else chart CLIENT_ENV), via stageFromClusterSpec.

Tests add alias-precedence coverage, a cli TestMain that unsets both stage vars for hermetic runs, and extend the env-resolution guard needles to TRACEBLOC_ENV. VERSION → 0.10.26.

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

[saadqbal]

Nice, careful PR. Alias-first is the right shape, and the tests are unusually good — I mutated both resolvers locally and every break got caught by name: dropping the CLIENT_ENV fallback fails TestResolveEnv and TestSessionEnvFallsBackToClientEnvOnlyWhenUnset, reversing precedence fails TestResolveEnvStageAlias and TestStageFromClusterSpec, and renaming api.StageEnvVar trips the doctor drift assertion. I also ran the suites with TRACEBLOC_ENV and CLIENT_ENV set to different values rather than the same one — the asymmetric case is the actual hazard the new TestMain guards, and it holds. Back-compat here is genuinely enforced, not just asserted.

One thing worth a follow-up push: the prose sweep stopped at the user-facing surface. auth.go:475 still says the target env is resolved "exactly like login (--env, then $CLIENT_ENV, then prod)" — you changed that chain and updated the flag help eleven lines below it in the same file. Same for the docstrings on the untouched readers that route through ResolveEnv: client.go:149/156/159, telemetry.go:105-107/119/147-149, and cli/doctor.go:117. I checked directly — sessionEnv with TRACEBLOC_ENV=dev and CLIENT_ENV unset returns dev, so those comments now describe a chain that isn't the one in the code. Nothing behavioural, but it's the exact class this repo keeps getting bitten by.

No markdown is affected — I grepped the whole tree and no README, CLAUDE.md, BUGBOT or runbook names either var, so your task-4 note is accurate. Nothing leaks on the public side either.

Minor: the body says the VERSION bump is 0.10.24 → 0.10.25; the diff is 0.10.25 → 0.10.26. Body only, probably a rebase.