[zkwentz]

Summary

This adds the openenvd: manifest contract and the unit's phase machine. They are the shared vocabulary for the rest of the stack.

• Zones. agent, services and observers each set a policy ceiling for network, resources and OCI runtime. Each container can only narrow its zone's ceiling. validate_manifest reports violations early. The kernel enforces the same narrowing anyway, through nested cgroup limits and per-container network namespaces.
• Zone rules a manifest can't override:
  • agent-zone egress is relays-only;
  • only observers may read assets or service state;
  • anything that reads assets runs only in frozen or grading;
  • an observer that reads both assets and the workspace has to be split into a runner and a verdict.
• Defaults from the top level. app and port default to the top-level fields of openenv.yaml, so an existing environment needs no new keys.
• Phases. The canonical phases are provisioning → ready → running ⇄ frozen → sealed → grading → closed, plus failed. sealed means the agent zone is gone and its outputs are fixed. Only the orchestrator resets; only the system fails a unit; the agent is never an actor.

Who may move the unit between phases

The agent appears on no arrow. The environment can only report done, and the move into grading waits for the kernel to report the agent zone empty.

Test plan

• 18 passed.

Stack

Part of openenvd on kernel primitives (#1053). Review bottom-up; each PR shows only its own layer.

1. openenvd 1/5: manifest contract and unit phases #1383: Contract and phases ← this PR
2. openenvd 2/5: cgroups and the isolation preflight #1385: cgroups and the isolation preflight
3. openenvd 3/5: confinement (seccomp, OCI, shim, forwarders, custody) #1416: Confinement: seccomp, OCI, shim, forwarders, custody
4. openenvd 4/5: relays and the external surfaces #1386: Relays and surfaces
5. openenvd 5/5: unit assembly, daemon, enforcement check and live tests #1387: Unit, daemon, check, live tests

Deployment assumption: openenvd ships in every image. Run privileged (a microVM in production, or docker run --privileged in development) and it isolates. Run any other way and it logs isolation disabled and serves the environment exactly as before.

The trace machinery (hash-chained trace, seal, harness self-report cross-check, /observe) is parked on zkwentz/openenvd-with-trace and is out of this stack's scope.

🤖 Generated with Claude Code

---

Note

Low Risk
New library-only contract and state machine with no runtime wiring yet; changes are validated by tests and do not alter existing environment serving paths.

Overview
Introduces the first openenvd layer: a typed openenvd: manifest contract and a unit phase machine, so later stack pieces share one vocabulary for isolation and lifecycle.

Manifest contract adds Pydantic models for agent / services / observers zones (network, cgroup resources, OCI runtime ceilings with per-container narrowing), container specs, and parse_manifest / load_manifest from openenv.yaml (with top-level app / port inherited when omitted). validate_manifest rejects unsafe or inconsistent configs up front—e.g. agent egress locked to relays-only, required env container, observer-only reads, asset reads only in frozen / grading, and rules that split combined asset+workspace observers.

Phase machine implements canonical phases (provisioning → … → closed, plus failed) with PhaseMachine enforcing who may transition (orchestrator, environment, system—not the agent), history, and PhaseError on illegal moves.

Exports are wired through openenv.core.openenvd; 18 tests cover defaults, validation failures, resource narrowing, and transition rules.

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

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit bc89e2c. Configure here.}

[cursor]

Alignment Review Report

Scope: commits 8d3455a...bc89e2c9 (the two commits unique to this PR) — src/openenv/core/openenvd/{__init__,contract,phases}.py + tests.

Automated Checks

• Lint: PASS — usort check, ruff format --check, and ruff check are all clean on the PR's files (src/openenv/core/openenvd/, tests/core/test_openenvd/). The repo-wide lint.sh run does report ~60 files needing formatting, but none of them are files this PR touches — pre-existing drift elsewhere in the tree.
• Debug code: CLEAN — no prints, TODO/FIXME/HACK, or debugger statements in the PR's files. (check-debug.sh does flag pre-existing print(...)/TODO occurrences elsewhere in src/, unrelated to this change.)
• Tests: all 18 new tests pass (tests/core/test_openenvd/). I also ran the full suite before/after this PR's commits — the only failures (tests/envs/test_websockets.py::test_protocol_client_state, ::test_protocol_client_multiple_episodes) reproduce identically on the pre-PR base commit, so they're pre-existing and unrelated.

Open RFCs Context

• RFC 1053 ("openenvd — Privileged Environment Sidecar with Policy-Scoped Surfaces", filed as GitHub issue #1053, not in rfcs/, status: open/under discussion, authored by @zkwentz, with unresolved review comments from @victorbarres) is the RFC this PR's stack implements (PR body: "Part of openenvd on kernel primitives (#1053)"). See the RFC Conflicts section below — the shipped design has diverged substantially from the RFC text.
• Other RFCs in Draft/In Review that touch adjacent ground: RFC 001 (dual API boundary, agents-cannot-reset — directly relevant, see below), RFC 005 (harness security boundary, which RFC 1053 explicitly proposes to subsume), RFC 008 (normalized manifest / openenv.yaml validation, relevant since this PR adds a new top-level openenvd: key).

Tier 1: Fixes Required

• src/openenv/core/openenvd/contract.py:232-233 (Zones._zone_defaults) — High severity, independently reproduced (also caught by Bugbot's automated review above): any manifest that sets a field under zones.agent.network other than egress/allow (e.g. the documented model field) silently resets the whole policy to NetworkPolicy()'s own default (egress="none") instead of the agent zone's relays-only default, because merged.setdefault("network", ...) only fills in the key when it's entirely absent, not per-field. validate_manifest doesn't catch the resulting "none" either, since it only rejects "allowlist"/non-empty allow. This silently drops the exact guarantee the module exists to enforce ("every call out of the agent zone crosses a relay"). Needs a field-level merge, and/or validate_manifest should require egress == "relays-only" for the agent zone explicitly rather than only forbidding wider settings.
• github-code-quality[bot]'s inline finding at contract.py:67 ("non-iterable used in for loop", pointing at the Resources.within/"Resources" string annotation) looks like a static-analysis false positive on investigation — the for name in ("memory_mb", "pids", "cpu") tuple is plainly iterable. No action needed unless you see a different interpretation.

Tier 2: Alignment Discussion

Principle Conflicts

None identified. The phase machine's Actor enum explicitly excludes the agent ("the agent is not an actor" — phases.py docstring), and the contract hard-fixes agent-zone egress to relays-only and forbids agent containers from declaring reads/expose/state/output. This is a genuine structural strengthening of "agents cannot reset" / the dual-API-boundary invariant (INVARIANTS.md, authored by @Darktex) rather than a conflict with it — worth calling out as a positive, not just absence of a negative.

RFC Conflicts

ALIGNMENT FLAG: Shipped contract vocabulary and scope diverge from the open RFC it implements

• Principle/RFC at stake: RFC 1053 ("openenvd — Privileged Environment Sidecar with Policy-Scoped Surfaces", GitHub issue #1053, still open, not yet accepted)
• The concern: RFC 1053's design (as currently written) is built around four named principals (orchestrator, agent, grader, observer) each minted a surface (SurfacePolicy with tools/fs_read/allow_lifecycle/allow_privileged_exec) declared under openenvd.surfaces.* in openenv.yaml. The shipped contract instead introduces zones (ZoneKind: agent/services/observers) with containers, cgroup Resources, NetworkPolicy egress tiers, and an OCI RuntimePolicy — none of which appear in the RFC text — declared under openenvd.zones.*. Two specific gaps stand out: (1) there is no grader zone/principal at all, even though "graders need affordances the agent must never have" is the RFC's primary motivating problem (RFC Problem 2) — services doesn't obviously map onto it; (2) the entire unit phase machine (provisioning → ready → running ⇄ frozen → sealed → grading → closed, plus failed) is a wholly new abstraction with no mention in the RFC text at all. Only privileged_assets: {name: path} and the top-level enabled/app/port keys match the RFC verbatim. Separately, @victorbarres's still-unanswered RFC comments ("how does a surface know who's calling", "what does reset actually reset given concurrent sessions", "which privileges does this need") aren't addressed by this contract — the zone/namespace model may well be a better answer to the first question than the RFC's same-host /mcp vs /mcp/grader split, but that's not written down anywhere reviewers can compare it against.
• Why this matters: this isn't necessarily wrong — the zones/phases design may be a deliberate evolution since the RFC was filed — but as written, a reviewer comparing PR against RFC text would see materially different abstractions, and the RFC's core "grader surface" goal appears unaddressed. Since RFC 1053 is still open, this is exactly the kind of divergence worth surfacing now rather than after all 5 stacked PRs land.
• Suggested reviewer: @zkwentz (RFC 1053 author and PR author — best positioned to say whether this is an intentional redesign that should be reflected back into the RFC text) and @victorbarres (raised the still-open surface-authentication / reset-semantics questions this contract's zone model bears on)

Summary

• 1 mechanical issue to fix (the silent agent-egress-default bug; the CodeQL non-iterable flag appears to be a false positive)
• 1 alignment point for human review (invariant-strengthening is a plus, noted for visibility)
• 1 RFC conflict to discuss (zones/phases vocabulary vs. RFC 1053's principals/surfaces vocabulary, and the missing grader surface)

  

_{Sent by Cursor Automation: Pre-review}