Docs: cover microvm sandbox support for kagent 1.x

[Rachael-Graham]

Two published pages tell a reader that a microvm WorkerPool cannot run kagent agents. kagent#2918 made it work, so both pages now steer readers away from a supported configuration.

This is a correction to two pages rather than a new page.

The defect

operations/tune-agent-substrate.md states it twice, most directly under Keep pools on the gvisor class: "kagent compiles every ActorTemplate to the gvisor class and to a SandboxConfig named exactly gvisor-default. Placement never relaxes the class constraint, so Workers in a microvm pool accept no kagent Actor, and the pool sits idle while turns time out." The page's introduction repeats it: "Leave the sandbox class on gvisor. A pool set to any other class sits idle while turns time out."

substrate-runtime/sandboxing.md carries the same claim in a blockquote: "kagent generates ActorTemplates that use the gvisor class. Keep a WorkerPool that backs kagent Harnesses on gvisor."

Both were accurate when written. Neither is now.

What the controller does

For every harness type, the controller resolves spec.substrate.workerPoolRef in the Harness and AgentTemplate namespace, and the pool's spec.sandboxClass selects the ActorTemplate's sandbox configuration.

WorkerPool sandboxClass	ActorTemplate sandbox class	SandboxConfig name
Empty or gvisor	SANDBOX_CLASS_GVISOR	gvisor-default
microvm	SANDBOX_CLASS_MICROVM	microvm

Those names follow Agent Substrate v0.2.0-beta5's standard gVisor installation and its MicroVM setup convention. They are neither API-level defaults nor discovery: Substrate requires an explicit name and rejects a missing SandboxConfig or a class mismatch.

Behavior the API does not announce

• Selecting microvm installs nothing. An operator must install the matching cluster-scoped SandboxConfig and provision compatible Workers and runtime assets. kagent configures no Kubernetes RuntimeClass and fetches no assets. A microvm SandboxConfig expects several assets rather than one, including cloud-hypervisor, kata-kernel, and kata-image, which sandboxing.md already documents.
• Workers must be KVM-capable, which is a node property rather than a chart value.
• The sandbox class is part of revision identity. Switching a pool between gvisor and microvm produces a distinct ActorTemplate identity and its own golden snapshot, instead of reusing the previous one. A reader needs this to understand why switching prepares a fresh snapshot rather than reusing the pool's existing state.
• Preparation failures now report through status. The pull request improved error reporting around sandbox preparation, so a misconfigured pool surfaces as a condition rather than as the silent idling the current page describes.
• The Helm surface is three values together: controller.substrate.enabled, substrateWorkerPool.sandboxClass, and a matching substrateWorkerPool.workerImage. Pairing microvm with a ateom-gvisor image is the mistake most likely to be made, so state the pairing rather than leaving it implied.

What to check before starting

This needs a live cluster with the microvm prerequisites installed, which is the hard part of the task rather than the writing. Upstream validated golden-snapshot preparation, pause/resume, suspend/resume, and switching a pool's class between the two.

1. Read docs/architecture/configuration-and-compilation.md in the kagent repository, under WorkerPool sandbox selection.
2. Confirm the SandboxConfig names against the Substrate version the docs target, rather than against the table above.
3. Run an agent on a microvm pool end to end, then switch the pool's class and observe what happens to the revision and the snapshot.
4. Confirm what a misconfigured pool reports now, so the page can replace "sits idle while turns time out" with the real symptom.

Done when

• Both false claims are gone: the Keep pools on the gvisor class section and its introduction on tune-agent-substrate.md, and the blockquote on sandboxing.md.
• The class-to-SandboxConfig mapping is documented, with gvisor named as the default.
• The operator prerequisites are stated plainly, including that kagent installs none of them.
• The image pairing is stated alongside sandboxClass.
• Revision identity and snapshot behavior on a class switch are covered.
• Every claim was verified on a cluster running both classes.