An environment is a label, not a folder. The vocabulary is closed to dev, test, staging, prod and orchestrator. orchestrator is the local, unset default execution environment. Values are lowercase and match [a-z][a-z0-9-]{0,31}. A value that is not in the list is rejected, never mapped, so production, PROD and staging are all refused rather than read as prod.
One state root can serve several environments. The environment changes what a run may touch, not where the state lives.
#What changes between them
The vault allow-list. A credential may be stored at any time, but it may only be injected into a run whose effective environment is in its list. The default is every non-prod environment; prod requires an explicit include. Set the list when you write the asset.
npx tsx orchestrator/cli.ts vault set acme --type credential --envs dev,staging username=... password=...
npx tsx orchestrator/cli.ts vault list
The Robot binding. A prod-effective job may only land on a robot whose own environment is prod. For every other job environment any robot is eligible, whether it declares an environment or not. A robot's environment can be set at registration or cleared with a null heartbeat, which re-opens non-prod eligibility. No path defaults an unset robot to prod.
Deployments. An activation carries an environment. A label-pinned dispatch may execute an activation only when its environment matches the dispatch's effective environment. The effective environment resolves in one order: the job's parameters.env.TS_ENVIRONMENT, then the process TS_ENVIRONMENT, then orchestrator.
The human continuation. The environment recorded on an Action's resume spec becomes TS_ENVIRONMENT for the run the decision dispatches. The mailbox continuation's environment must match its activation too.
#How the vault interacts with environments
Injection is resolved at the dispatcher seam, before any queue claim and before any Robot spawn. The decision reads the environment and the credential's allow-list only. It never reads the sealed crypto form. Three refusals are possible: the name is not in the vault, the credential is not allowed in this environment, or a prod run asks for a credential that was not explicitly included for prod. Each is a business-class refusal that names the credential. The run produces no Robot and no evidence.
What is recorded is lineage, not values: the credential's name and a 12-hex fingerprint over the sealed item, so a rotation or a value change moves the fingerprint. jobs show <id> prints that lineage. jobs list --credential <name> or --fingerprint <fp> answers the inverse question, which runs used this credential.
The Studio has a helper that emits the Robot's credential channel for one environment. It skips and names any vault entry not allowed there rather than failing the whole run:
npx tsx orchestrator/vault-env.ts --root orchestrator/state --env staging
#Things that catch people out
There is no environment CLI verb. The vocabulary is enforced in code at the provisioning and registry seams. Activations (and therefore the environment bindings on them) are managed through the Orchestrator server's /deployments routes, not this CLI.
An environment mismatch is a deployment-class refusal that happens before the spawn, so a mismatched job leaves no run and no evidence. Read jobs show <id>; the failure class is deployment.