[Epic] Define a portable agent runtime contract across sandbox images and runtime providers

## Problem Statement

NemoClaw currently has two different sandbox image paths:

- Stock onboarding selects complete, immutable NemoClaw-managed images.
- Custom --from onboarding builds a user-supplied Dockerfile through the Docker provider.

The managed path has versioned image, startup-profile, runtime-provider, lifecycle, and recovery contracts. The custom path remains separate and must reproduce managed implementation details to receive equivalent behavior. Those details include the /usr/local/bin/nemoclaw-start executable, the /sandbox layout, agent-specific configuration materialization, expected process shapes, and runtime identity and filesystem assumptions. Native rootless Podman accepts exact managed images but does not qualify custom --from Dockerfiles.

There is no supported contract that cleanly distinguishes:

- What an agent sandbox image must provide.
- What NemoClaw supplies at startup.
- What a runtime provider must enforce.
- What OpenShell owns for identity, workspace ownership, isolation, and lifecycle.
- How NemoClaw verifies compatibility without requiring a NemoClaw-derived image.

As a result, image compatibility depends on implementation details. Adding another image or runtime can require copying NemoClaw startup code or adding provider-specific branches instead of implementing one stable boundary.

## Desired Behavior

Define one versioned, portable agent runtime contract consumed by NemoClaw-managed images and qualified custom images across supported runtime providers.

The contract separates ownership as follows:

- The image publisher owns the agent software and declared runtime dependencies.
- The NemoClaw agent definition owns agent commands, state, health, and integration requirements.
- NemoClaw owns non-secret desired-state planning, compatibility validation, and exact workload receipts.
- The runtime provider owns workload creation, lifecycle, recovery, and exact cleanup.
- OpenShell owns runtime identity, workspace preparation, isolation, and platform-specific filesystem behavior.
- Credentials remain in the existing OpenShell credential boundary.

NemoClaw-managed images remain the secure, tested default. A qualified custom image is the proof that the contract is independent of the image source, not a replacement for managed images.

The first runtime proof should use the same exact OpenClaw fixture image and contract through Docker and native rootless Podman. The fixture must not be built from NemoClaw Dockerfiles and must not contain /usr/local/bin/nemoclaw-start.

## Product Decision Requested

Proposed decision: Accept the portable contract direction, beginning with an inert contract and one Docker and Podman qualification fixture.

Before implementation, maintainers must confirm:

- The accountable owner.
- The first supported consumer.
- Whether startup authority comes from the OCI entrypoint, the agent definition, or an explicit OpenShell create request.
- How non-secret configuration is materialized without embedding the current managed startup runtime.
- Required image provenance and attestation.
- Contract-version compatibility and removal policy.
- The exact Docker and Podman hosts, operations, and limitations covered by the first qualification.
- The evidence required before any public support claim.

This issue is not accepted product scope until a maintainer records that decision.

## Contract Requirements

The contract must define:

- Agent identity and compatible version.
- Exact image identity and provenance.
- Startup command authority and tokenized argument representation.
- Working directory, home, configuration, and state locations.
- Runtime identity requirements without assuming a fixed numeric UID or account name.
- Required OpenShell workspace and filesystem capabilities.
- Non-secret startup configuration and credential references.
- Health, readiness, stop, restart, and recovery behavior.
- Version negotiation and unsupported-contract diagnostics.
- Exact workload receipts and cleanup authority.

Use the existing AgentDefinition, managed startup profile, workload-source, and RuntimeProviderBundle structures as the source boundaries. Do not introduce a parallel agent manifest, image registry, lifecycle ledger, or provider-specific branch in central orchestration.

## Acceptance Criteria

- [ ] A maintainer records the product decision, accountable owner, first consumer, support status, and compatibility policy.
- [ ] The contract is versioned, bounded, deterministic, and credential-free.
- [ ] Managed images and qualified custom images consume the same contract semantics.
- [ ] Docker and native rootless Podman advertise and validate the same contract version and capability meanings.
- [ ] One startup authority is documented; conflicting OCI and declared commands never produce guessed behavior.
- [ ] Startup commands remain tokenized arguments and cannot introduce shell interpretation.
- [ ] Exact image digest, agent identity, platform, and contract version are verified before mutation.
- [ ] One qualified OpenClaw fixture image is not derived from NemoClaw Dockerfiles and does not contain nemoclaw-start.
- [ ] The same exact fixture and contract complete startup, readiness, restart, recovery, and cleanup through Docker and native rootless Podman.
- [ ] Podman qualification runs with Docker unavailable and proves that no Docker socket, command, compatibility layer, or fallback is used.
- [ ] The fixture runs with a non-root identity without requiring a fixed sandbox UID or username.
- [ ] Runtime-owned private state can remain mode 0700; the design does not require blanket group-writable permissions.
- [ ] Credential values do not enter the contract, image metadata, command arguments, plans, logs, receipts, or retained artifacts.
- [ ] Missing, malformed, mutable, conflicting, secret-bearing, and unsupported contracts fail before sandbox creation.
- [ ] A timeout after possible creation triggers exact identity reconciliation rather than a blind retry.
- [ ] Cleanup removes only resources proven to belong to the exact attempt and provider.
- [ ] Stock managed-image onboarding retains regression coverage on Docker and Podman.
- [ ] Existing custom-Dockerfile behavior remains explicit during any migration.
- [ ] Documentation distinguishes compatible, qualified, and supported images and lists the exact provider limitations.
- [ ] Native Kubernetes and OpenShift remain unsupported until separately accepted and qualified.

## Capability Slices

### 1. Contract and inert validation

Define the schema, source-of-truth mapping, capability negotiation, validation, errors, and conformance fixtures without changing production workload selection.

Acceptance requires deterministic proof that valid fixtures are accepted and malformed, secret-bearing, conflicting, mutable, and unsupported contracts are rejected.

### 2. Docker qualification

Run one non-NemoClaw-derived OpenClaw fixture through startup, readiness, restart, interruption recovery, and exact cleanup under the Docker provider.

This slice does not activate a public custom-image surface.

### 3. Native rootless Podman qualification

Run the same exact fixture and contract through the same lifecycle with Docker unavailable. Prove provider-neutral semantics, exact Podman ownership, and no Docker fallback.

This slice does not claim support beyond the qualified host and operation matrix.

### 4. Supported activation

Expose the accepted contract-based image path through the declarative onboarding configuration only after Docker and Podman qualification pass and maintainers accept the activation evidence.

Additional agents, platforms, and lifecycle operations require their own accepted qualification.

## Related Work

- NVIDIA/NemoClaw#7744 — provider-neutral, buildless managed onboarding and native Podman.
- NVIDIA/NemoClaw#9140 — activation of stock buildless managed onboarding.
- NVIDIA/NemoClaw#9145 — activation of supported native Podman for qualified managed images.
- NVIDIA/NemoClaw#10904 — accepted declarative onboarding configuration.
- NVIDIA/NemoClaw#9873 — external-gateway lifecycle using a stock managed image.
- NVIDIA/OpenShell#848 — custom sandbox startup command.
- NVIDIA/OpenShell#1268 — protected creation-time file injection.
- NVIDIA/OpenShell#1959 — runtime-selected sandbox identity.
- NVIDIA/OpenShell#2526 — OCI working directory and workspace behavior.
- NVIDIA/OpenShell#2761 — persistent workspace ownership under sidecar topology.

## Constraints and Non-goals

- Do not claim support for arbitrary images.
- Do not claim native Kubernetes or OpenShift support.
- Do not remove NemoClaw-managed images.
- Do not weaken current credential, policy, provenance, process, or filesystem controls.
- Do not solve workspace ownership by replacing every mode-0700 directory with group-writable permissions.
- Do not implement missing OpenShell capabilities inside NemoClaw.
- Do not add Docker or Podman branches to central orchestration.
- Do not claim complete Docker and Podman feature parity beyond the qualified matrix.
- Do not activate all agents or platforms in the first slice.

## Security and Privacy Impact

Sandbox images and their declarations are untrusted input. Validation must fail closed on mutable identity, contract mismatch, command ambiguity, unsafe paths, missing non-root execution, and unverifiable readiness.

Credential values remain in the existing trusted credential boundary. The portable contract contains only references and non-secret intent.

Lifecycle operations must bind creation, readiness, recovery, and cleanup to exact image, sandbox, runtime provider, lifecycle generation, and attempt identities. Name-only adoption or deletion is not acceptable.

Provider parity must include negative evidence. In particular, the Podman path must not acquire Docker authority or silently fall back to Docker when a required capability is absent.

## Implementation Idea

Add a portable contract variant to the existing workload-source model only after the design is accepted. Reuse agent-definition fields and the secret-free managed startup profile where their ownership already matches.

Let runtime providers advertise the contract versions and capabilities they can enforce. Keep provider-specific execution behind RuntimeProviderBundle. Begin with an inert validator, then qualify the same custom fixture under Docker and Podman before public activation.

## Category

Platform

## Checklist

- [x] I searched existing issues and found no exact duplicate.
- [x] I described the problem and desired behavior.

Start by reading the existing AgentDefinition, managed startup profile, workload-source, and RuntimeProviderBundle structures named in the issue, then confirm the maintainer product decision and ownership boundaries. Begin with the inert contract validator and conformance fixtures before changing workload selection. Done means deterministic validation evidence exists and the same fixture lifecycle is qualified through Docker and native rootless Podman without public support claims beyond the accepted matrix.

Written by the indexing model from the issue text.