UHP Environments
Environments let many sessions reuse one built project without turning the session workspace into shared mutable state.
Page reviewed 4 Oct 2026 Source and review policy
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.
- Let a successful build become active, or explicitly activate an earlier ready version to roll back.
- Attach it to a harness or select it for one task.
- A new session reads the active version through the read-only mount; an already-running turn keeps its starting version.
Build records expose status, stage and log information. Versions are immutable once built; activating another version provides rollback without rewriting an existing build.
Choosing and diagnosing a build
Section titled “Choosing and diagnosing a build”The following workflow is derived from the versioned endpoint contract, checked 4 October 2026; it is not a live server test.
| Observation | Check next | Meaning |
|---|---|---|
Discovery omits or disables environments | Stop Environment-specific requests | The server has not advertised this optional surface. |
Source upload succeeds but a task says environment_not_ready | Start a build, then inspect its build record | Uploading source does not install dependencies or publish a ready version. |
| A build is still running | Read builds/{version} status, stage and log | Build acceptance is not completion; one build runs per Environment at a time. |
| A new build fails while an older version was active | Inspect the active version separately from latestVersion | A failed build does not replace the previously usable version. |
A package check returns 404 | Use documented build/registry checks | Package checking is optional; its absence does not disable Environments. |
| Source edits are not visible to a task | Compare source, active build and turn version | Edits require a new build; existing turns retain their starting version. |
Use an Environment when several sessions need the same project and dependency set. Use the session workspace for generated files and per-task edits. Putting private per-session output into shared project state crosses the intended ownership boundary.
Selecting an Environment
Section titled “Selecting an Environment”Plan a rollout and rollback without losing task provenance
Section titled “Plan a rollout and rollback without losing task provenance”Suppose several sessions share a built project. Uploading a changed dependency file changes the source, not the version a task reads. Record the Environment ID, active version and build outcome before asking users to retry.
- Build the changed source and inspect the build record to a terminal outcome.
- Compare
version(active) withlatestVersion(newest attempted), especially after failure. - Let a new turn read the active version; do not assume an already-running turn changes underneath you.
- For rollback, activate an earlier ready version rather than editing a published layer in place.
- Preserve the response’s
metadata.environmentand relevant version evidence alongside the task result.
| Symptom | Interpretation to check |
|---|---|
| One running task sees older files | Its starting version may correctly remain pinned |
| Source looks updated but all new tasks see old files | The source may not have been successfully built/activated |
| Latest build failed while tasks still run | An older active version can remain usable |
| Task writes fail under the project mount | Read-only enforcement may be working; write outputs to the session workspace |
The Environments contract supplies the version/activation semantics. The operational checklist here keeps source edits, build acceptance and task-visible state distinct.
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.
Related reading
Section titled “Related reading”Use the HTTP API map for the complete Environment endpoint family and security for build privileges, read-only mounts and path confinement.