[Epic] Support Pi as a first-class NemoClaw agent runtime

## Summary

Make Pi a supported NemoClaw agent runtime alongside OpenClaw, Hermes, and LangChain Deep Agents Code.

A user must be able to select Pi during canonical onboarding. NemoClaw must manage Pi through the supported sandbox lifecycle without coupling Pi to one compute runtime.

## Open-source product scope

This epic defines the public open-source NemoClaw product surface. NVIDIA-internal or other organization-specific deployment policies may govern how downstream users deploy Pi, but they are not approval gates for upstream implementation or release.

The supported NemoClaw path still runs Pi inside an OpenShell sandbox. NemoClaw does not install or run Pi directly on the user host.

## Delivery target

Complete the supported open-source Pi release during the two-week execution window from 2026-08-12 through 2026-08-25.

## Context

NemoClaw already uses Pi in contributor and CI workflows:

- The root project pins `@earendil-works/pi-coding-agent` and exposes it through `npm run agent`.
- Trusted advisor and conflict-resolution workflows use the Pi SDK.
- Those workflows use a digest-pinned OpenShell community Pi sandbox image.

These uses show technical compatibility. They do not establish Pi as a supported NemoClaw agent runtime.

The managed-image publication and selection contracts from #7756 and #7772 are now on `main`. Protected buildless qualification from #8234 and manifest-derived state handling from #8143 are also on `main`. Pi must consume those landed contracts.

Podman epic #7744 remains the coordination point for native Podman activation and the all-shipped-agent gate. Closed, unmerged PR #7872 is not a design source.

## Problem Statement

Users cannot select Pi through the supported NemoClaw onboarding path. Pi has no NemoClaw agent manifest or defined product lifecycle.

Manual Pi sandbox configurations do not define:

- artifact ownership and update cadence;
- supported inference providers, models, and API families;
- credential custody and network policy;
- tool, skill, extension, and prompt trust boundaries;
- persistent state, backup, rebuild, and upgrade behavior;
- status, logs, diagnostics, and failure recovery;
- platform and compute-runtime compatibility;
- managed-image publication and release qualification.

Without these contracts, each Pi deployment is a custom solution that NemoClaw cannot qualify or support.

## Desired Behavior

A user can select Pi through interactive onboarding or a supported non-interactive command such as:

```bash
nemoclaw onboard --agent pi
```

Stock onboarding selects an exact Pi managed-image digest. It does not build a repository Dockerfile on the user's host.

NemoClaw creates an OpenShell sandbox with a pinned Pi runtime. Pi uses managed inference without receiving the upstream provider credential.

The public NemoClaw lifecycle must identify the sandbox as a Pi sandbox. Supported commands must cover onboarding, connection, status, logs, rebuild, backup, upgrade, and destroy behavior where applicable.

Pi must support one documented interactive terminal flow and one documented non-interactive flow.

## Compute-runtime boundary

Pi is an agent runtime. Docker, Podman, and future providers such as MXC are compute runtimes.

- Pi-specific code owns the agent manifest, startup profile, configuration, state, tools, policies, and entry points.
- Compute-runtime providers own image launch, lifecycle mutation, recovery, snapshot, and cleanup mechanics.
- Pi code must not branch on Docker or Podman.
- Docker or Podman code must not branch on Pi.
- Shared managed-image, bootstrap, lifecycle, and inference contracts compose the two dimensions.

A reviewed Dockerfile may remain a CI image-build source. It is not the stock onboarding mechanism.

Pi does not need to wait for Podman activation unless the accepted v1 scope includes Podman at launch. If Pi ships first, #7744 must include Pi in its all-shipped-agent activation gate.

## Product Decision Required

Maintainers must accept this epic before Pi becomes a supported product surface. The accepted decision must name:

- the product and engineering owners;
- the canonical agent ID;
- the supported Pi package, managed image, build source, and distribution source;
- the version pin and update cadence;
- the supported host platforms and architectures;
- the supported compute runtimes at Pi launch;
- whether Podman is launch scope or joins when #7744 activates;
- the supported inference providers, models, and API families;
- the owner of each lifecycle and persistent-state boundary;
- the credential, network, filesystem, tool, skill, and extension policies;
- the managed-image catalog, publication cohort, and startup-profile contracts;
- the release qualification environment and required evidence;
- the support lifecycle and compatibility policy after launch.

## Minimal v1 Scope

- One Pi agent manifest under `agents/pi/`.
- One integrity-verifiable Pi runtime package and managed OCI image.
- Exact managed-image digests for each accepted platform and architecture.
- Registration in the managed-image catalog and atomic publication cohort.
- Interactive and non-interactive terminal execution.
- Managed inference through the supported `inference.local` route.
- A Pi-specific baseline network policy.
- Declared persistent and reconstructible state.
- Shared, compute-runtime-neutral onboarding, inventory, status, logs, recovery, rebuild, backup, upgrade, and destroy integration.
- Actionable errors for unsupported models, missing configuration, inference failure, runtime startup failure, and unsupported compute runtimes.
- Targeted unit, integration, package-contract, and live E2E coverage.
- User documentation, troubleshooting, compatibility limits, and release material.

## Constraints and Non-goals

- Do not add a shared multi-agent manifest. Pi must have its own agent manifest and evidence.
- Do not treat the existing contributor dependency or CI image as product approval.
- Do not use an unpinned package, image tag, or runtime auto-update path.
- Do not build the stock Pi image from a Dockerfile during user onboarding.
- Do not expose upstream provider credentials to the Pi sandbox.
- Do not add a Pi-specific Docker, Podman, gateway, lifecycle, snapshot, or recovery branch.
- Do not use closed, unmerged #7872 as a design source. Use the provider-neutral contracts on current `main` and coordinate remaining Podman activation through #7744.
- Do not refactor every agent integration as part of this epic.
- Messaging channels and a dashboard are outside v1 unless the accepted product decision adds them.
- Replacing the repository-pinned contributor command or existing Pi CI automation is outside v1.

## Implementation Idea

Use the existing manifest-first agent architecture:

```text
agents/pi/
manifest.yaml
start.sh
generate-config.ts
policy-additions.yaml
Dockerfile # reviewed CI image-build source, if required
Dockerfile.base # reviewed CI base-image source, if required
```

Add candidate Pi artifacts to agent discovery, managed-image validation, and repository-map contracts without making Pi publicly selectable or adding it to the active release cohort.

Pi must provide data for the landed startup-profile, image-runtime, protected-qualification, and manifest-derived state contracts from #7756, #7772, #8234, and #8143. It must not add compute-runtime orchestration.

Reuse the existing Pi package or OpenShell community image only after maintainers accept its ownership, integrity, lifecycle, startup-profile, and compatibility contracts.

Coordinate remaining compute-runtime activation with #7744. Final public selection and atomic cohort activation belong to #8818. Do not make the Pi release depend on unfinished Podman activation unless the accepted product decision requires Podman at launch.

## Acceptance Criteria

- [ ] Maintainers accept the product decision and record every required owner and lifecycle contract.
- [ ] Carlos Villela reviews the selected Pi runtime, managed-image, startup-profile, and agent-specific lifecycle boundaries.
- [ ] Interactive onboarding and `nemoclaw onboard --agent pi` select and persist the Pi agent.
- [ ] Stock onboarding selects an exact managed-image digest without a host Dockerfile build.
- [ ] Pi is registered in the managed-image catalog and atomic publication cohort.
- [ ] A fresh supported installation starts the pinned Pi runtime through a documented public command.
- [ ] Interactive and non-interactive Pi sessions complete a tool-using task through managed inference.
- [ ] The Pi sandbox does not contain the upstream provider credential.
- [ ] Inventory, status, logs, diagnostics, rebuild, backup, upgrade, and destroy behavior identify and preserve the declared Pi contracts.
- [ ] Pi integration contains no Docker- or Podman-specific lifecycle branch.
- [ ] Policy tests permit only the required inference and tool endpoints.
- [ ] Negative tests deny undeclared network access, host control, and credential access.
- [ ] Package and image identities are pinned and integrity-verifiable.
- [ ] Supported host platforms, architectures, and compute runtimes pass the accepted compatibility matrix.
- [ ] If Podman is not Pi launch scope, #7744 records Pi as required before Podman activation.
- [ ] A fresh live environment reproduces onboarding and the acceptance task from the exact candidate commit.
- [ ] Documentation explains onboarding, operation, state, security boundaries, compatibility limits, and recovery.
- [ ] A documentation writer reviews the implementation and documentation evidence.
- [ ] #8818 atomically enables Pi in the supported inventory and managed-image release cohort after every prerequisite is complete.

## Work Tracking

- [ ] #7926 — [Pi 1/8] Accept product scope, ownership, threat model, and compatibility matrix.
- [ ] #7925 — [Pi 2/8] Add the pinned Pi runtime, image, manifest, and entry points.
- [ ] #7927 — [Pi 3/8] Integrate Pi onboarding, lifecycle, state, and recovery.
- [ ] #7930 — [Pi 4/8] Integrate managed inference and credential handling.
- [ ] #7924 — [Pi 5/8] Define Pi tool, skill, extension, filesystem, and network policies.
- [ ] #7928 — [Pi 6/8] Add deterministic tests and live E2E qualification.
- [ ] #7929 — [Pi 7/8] Document Pi onboarding, operations, and release support.
- [ ] #8818 — [Pi 8/8] Activate Pi in supported inventory and release cohort.

## Category

Feature

## Checklist

- [x] I searched open and closed issues and this is not a duplicate.
- [x] I described the problem and desired behavior.