Protocol
UHP Environments
Environments let many sessions reuse one built project without turning the session workspace into shared mutable state.
What an Environment is
Section titled “What an Environment is”An Environment is a project’s files plus installed dependencies, built once and reused by sessions. The server mounts the selected version read-only at a fixed path beside the session’s writable working directory.
The separation is deliberate: project state is reusable; task artifacts still come from the session workspace.
Lifecycle
Section titled “Lifecycle”- Create an Environment.
- Add/import project files.
- Build a version; the server installs declared dependencies.
- Make a ready version active.
- Attach it to a harness or select it for one task.
- Sessions read the active version through the read-only mount.
Build records expose status, stage and log information. Versions are immutable once built; activating another version provides rollback without rewriting an existing build.
Selecting an Environment
Section titled “Selecting an Environment”Harness and session objects use an ordinary environment field.
For a task, the patched UHP 2026-09-28 contract uses:
{ "metadata": { "environment": "henv_..." }}That task value overrides the harness default.
Upstream documentation drift
Section titled “Upstream documentation drift”The current tasks.md request-field table still shows a top-level environment field. PR #331 explicitly removed that request property, and the changelog, JSON Schema, conformance EN-05/EN-07 and HarnessRouter gateway all use metadata.environment.
This guide therefore treats the table row as stale documentation. A top-level environment is accepted only under the protocol’s unknown-field rule and is ignored by the patched reference implementation.
Trust boundary
Section titled “Trust boundary”A session MUST NOT be able to write into its Environment mount. Sessions sharing one Environment can read the same project bytes but do not share their writable working directories.
Conformance
Section titled “Conformance”The current package is 2026.9.28.post3. Environment checks are capability-gated Full checks; current source includes EN-01 through EN-09.