[Epic] Consolidate the experimental Portable runtime and lifecycle contract for OpenClaw and Hermes
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 715
Description
## Outcome
OpenClaw and Hermes use one shared experimental Portable lifecycle layer for rootless Podman authority, child-process environment, sandbox image builds, lifecycle orchestration, recovery, cleanup, diagnostics, and conformance tests.
Each agent adapter keeps its agent-specific image inputs, startup command, health and authentication checks, pairing behavior, state directories, user commands, and receipt authority.
## Product decision
- Keep the current OpenClaw and Hermes implementations until both paths have passing qualification evidence.
- Do not move Hermes onto `portable-demo-lifecycle.ts`.
- Extract only behavior that has the same contract for both agents.
- Preserve OpenClaw receipt schemas 1 through 4.
- Preserve Hermes receipt schema 5 and its agent discriminator.
- Do not migrate existing receipts only to complete this consolidation.
- #9200 remains the OpenClaw Portable qualification owner.
- #9211 remains the Hermes Portable qualification owner.
- #7744 remains the production native Podman architecture and support owner.
- Closed issue #9006 remains the predecessor for profile-wide runtime contract corrections.
- Passing tests establish evidence for the tested commit and environment. They do not establish product support.
## Design basis
The review at `b6e5936e6f87180caa0c5a74e32b0cf88016b881` found two valid agent-specific contracts and duplicated common orchestration:
- OpenClaw uses `src/lib/onboard/experimental/portable-demo-lifecycle.ts` and schema-4 receipt behavior.
- Hermes uses schema-5 receipt, onboarding, Podman authority, policy authority, build-context, and lifecycle modules under `src/lib/onboard/experimental/`.
- Hermes requires agent-specific port 8642 startup, Bearer-authenticated health checks, no device pairing, and `/sandbox/.hermes` state.
- PR #10023 demonstrates that builder compatibility and runtime authority must remain consistent across NemoClaw, OpenShell, and every child process.
The split was necessary for Hermes-specific authority. The duplicated runtime and lifecycle plumbing is the consolidation target.
## Implementation prerequisites
Do not start shared-layer implementation until all conditions pass:
- PR #10023, or an accepted replacement, corrects the Hermes Portable builder and runtime-authority failures.
- #9211 records one complete Hermes run on one GitHub-Verified `main` commit.
- #9200 records one complete OpenClaw run on one GitHub-Verified `main` commit.
- Each run covers install, fresh onboarding, OpenShell `Ready`, connect or launch, health, one inference request, stop and start, recovery, and receipt-owned uninstall.
- Each run proves that Docker fallback did not occur and unrelated container resources did not change.
P1 and P2 corrections are prerequisites. They do not complete this Epic without both lifecycle baselines.
## Shared lifecycle-layer responsibilities
The shared layer owns these contracts:
1. Resolve one rootless Podman authority for each operation.
2. Revalidate the socket, user, process, and runtime identity before a mutation.
3. Construct the runtime environment for every NemoClaw, OpenShell, builder, and lifecycle child process.
4. Select and invoke a builder whose capabilities match the Dockerfile or staged build context.
5. Coordinate common lifecycle locks, phases, recovery, cleanup, and error classification.
6. Dispatch receipt parsing and mutation authority through the selected agent adapter.
7. Produce common redacted diagnostics and conformance-test fixtures.
The shared layer must not contain OpenClaw- or Hermes-specific startup, authentication, pairing, health, state-directory, or user-command behavior.
## Agent-adapter responsibilities
Each adapter owns:
- agent identity and agent manifest;
- base image, Dockerfile, staged build context, and build-time settings;
- startup command, gateway port, and readiness or health criteria;
- authentication and credential handling;
- device-pairing behavior;
- persistent state directories;
- connect and launch behavior;
- receipt schema parsing and agent-specific identity fields;
- agent-specific policy and inference requirements.
OpenClaw and Hermes do not need feature parity. They need the same common lifecycle guarantees where both expose the operation.
## Security and resource invariants
- Never use Docker as a fallback for a Podman-owned operation.
- Never trust ambient `DOCKER_HOST`, `CONTAINER_HOST`, or another unvalidated runtime selector.
- Never use a sandbox or container name as mutation authority.
- Bind mutations to the full container ID, runtime socket, required labels, lifecycle generation, receipt, and sandbox registry.
- Fail closed on socket replacement, identity drift, duplicate resources, unknown receipt schema, receipt-agent mismatch, or live-state disagreement.
- Preserve unrelated Docker and Podman containers, images, networks, volumes, and services.
- Keep credentials, Bearer tokens, pairing state, and raw policy content out of logs and artifacts.
- Preserve private ownership, bounded files, durable receipt publication, and crash recovery.
## Capability slices
### Slice 1: Contract and ownership inventory
Map each current OpenClaw and Hermes responsibility to its source owner, test owner, and target shared or adapter boundary. Record intentional differences before source changes begin.
### Slice 2: Runtime authority and child environment
Create one shared authority descriptor and environment constructor. Make both agents use it for bootstrap, image build, OpenShell, onboarding, resume, status, and lifecycle commands.
### Slice 3: Sandbox image build contract
Create one builder-capability contract. Reject unsupported Dockerfile features before the build starts, or stage an equivalent compatible build context with deterministic tests.
### Slice 4: Shared lifecycle orchestration
Extract common locking, phase transitions, revalidation, recovery, cleanup, and diagnostics. Preserve each agent's receipt schema and mutation authority.
### Slice 5: OpenClaw and Hermes adapters
Move agent-specific image, startup, health, authentication, pairing, state, policy, and command behavior behind explicit adapters. Do not add an agent-specific conditional to the shared layer when an adapter owns the behavior.
### Slice 6: Cross-agent conformance matrix
Run the same applicable behavior contracts for OpenClaw and Hermes. Keep agent-specific assertions in their adapter suites.
### Slice 7: Activation and documentation decisions
Obtain independent security and documentation reviews. Record separate activation decisions in #9200 and #9211.
Create one accepted child issue per slice after the implementation prerequisites pass. Do not let two child issues change the same shared contract concurrently.
## Acceptance criteria
- [ ] The contract inventory identifies one owner for each current common and agent-specific behavior.
- [ ] OpenClaw and Hermes consume one runtime-authority and child-environment implementation.
- [ ] OpenClaw and Hermes consume one sandbox image builder-capability contract.
- [ ] OpenClaw and Hermes consume one common lifecycle orchestration layer.
- [ ] The shared layer contains no agent-specific startup, health, authentication, pairing, state-directory, or user-command behavior.
- [ ] Existing OpenClaw schemas 1 through 4 remain readable and enforce their current authority.
- [ ] Hermes schema 5 remains agent-discriminated and enforces its current authority.
- [ ] Deterministic tests reject Docker fallback, socket drift, receipt-agent mismatch, duplicate identity, unsupported builder features, and missing child-process selectors.
- [ ] The protected cross-agent matrix covers fresh onboarding, resume, status, connect or launch, health, inference, stop and start, recovery, destroy, and uninstall where each agent exposes the operation.
- [ ] One OpenClaw run and one Hermes run pass on the same GitHub-Verified `main` commit and accepted rootless Podman matrix.
- [ ] Unrelated Docker and Podman resources remain unchanged in both runs.
- [ ] Independent security review finds no unresolved blocking finding.
- [ ] #9200 and #9211 record their own experimental activation decisions.
## Non-goals
- Production native Podman support or buildless managed onboarding owned by #7744.
- Feature parity between OpenClaw and Hermes.
- One receipt schema for all agents.
- A migration from one agent lifecycle implementation to the other.
- Host image capture, quiesce, reseal, or immutable payload layout.
- ACP activation or qualification.
- A general support claim for the experimental Portable profile.
## Category
Platform
## Checklist
- [x] I searched open and closed issues.
- [x] This issue is not a duplicate of #9006, #9200, #9211, or #7744.
- [x] This issue records an accepted cross-agent architecture boundary.
Contributor guide
Assessment
This issue has not been assessed yet.