[Pi 3/8] Integrate Pi onboarding, lifecycle, state, and recovery

[prekshivyas]

Summary

Integrate Pi with the public, compute-runtime-neutral NemoClaw sandbox lifecycle.

Parent epic: #7923

Coordination epic: #7744

Landed dependency baseline: #7756, #7772, #8234, #8143, and #7718.

Depends on #7926 and #7925.

Target completion: 2026-08-25.

Problem Statement

Users cannot select Pi during onboarding. NemoClaw cannot persist or operate Pi as a known sandbox agent.

Without lifecycle integration, status, recovery, rebuild, backup, upgrade, and destroy behavior remain undefined.

A Pi-specific Docker or Podman path would duplicate lifecycle behavior and conflict with #7744's driver-neutral contracts.

Desired Behavior

Protected candidate and contract-test paths select the Pi agent and persist its identity in the sandbox registry. Public interactive selection and nemoclaw onboard --agent pi remain disabled until #8818.

Candidate onboarding selects the exact managed-image digest from #7925. It does not build a repository Dockerfile on the user's host.

Inventory and lifecycle commands identify the agent runtime as Pi. Each command delegates compute-runtime behavior through the selected provider bundle.

Delivery structure

This issue may land through multiple implementation PRs under one acceptance boundary:

1. Agent discovery, registry identity, candidate onboarding, connection, inventory, status, logs, and diagnostics.
2. Resume, recovery, rebuild, backup/restore, upgrade, and destroy through shared lifecycle and provider contracts.

Neither stream activates public Pi selection; #8818 owns activation.

Scope

• Agent discovery and interactive selection.
• Non-interactive onboarding input.
• Managed-image workload selection.
• Sandbox registry persistence for agent and compute-runtime identities.
• Connection and Pi terminal entry.
• Inventory, status, logs, and diagnostics.
• Rebuild, backup, restore, upgrade, and destroy behavior.
• Resume and failed-onboarding recovery.
• Pi-specific actionable errors.

Constraints and Non-goals

• Do not infer Pi for sandboxes that have no recorded agent identity.
• Do not infer compute-runtime identity from the Pi agent identity.
• Do not preserve state outside the accepted manifest.
• Do not add a Pi-specific Docker, Podman, gateway, lifecycle, snapshot, or recovery branch.
• Do not import Pi code into a compute-runtime provider.
• Do not use closed, unmerged feat(runtime): add native Podman support for all agents #7872 as a design source.
• Do not make Pi publicly selectable in this issue; [Pi 8/8] Activate Pi in supported inventory and release cohort #8818 owns activation.
• Do not add messaging channels or a dashboard unless the product decision includes them.
• Do not change other agents' lifecycle contracts.

Acceptance Criteria

• Protected candidate and contract-test onboarding paths select and persist pi while public selection remains disabled.
• Candidate onboarding selects an exact Pi managed-image digest without a host build.
• Protected qualification starts Pi through the exact candidate path; [Pi 8/8] Activate Pi in supported inventory and release cohort #8818 owns the documented public command.
• Inventory, status, logs, and diagnostics identify Pi separately from the compute runtime.
• Resume recovers a failed Pi onboarding without changing the selected agent or compute runtime.
• Rebuild and upgrade restore the accepted runtime, managed-image identity, and state.
• Backup and restore include only declared persistent state.
• Destroy delegates cleanup to the selected compute-runtime provider.
• Pi lifecycle code contains no Docker or Podman identity comparison.
• Unsupported agents or compute runtimes report actionable errors.
• Tests inject a non-Docker provider without changing Pi behavior.
• Tests cover fresh onboarding, resume, rebuild, backup, upgrade, and destroy behavior.

Category

Feature

Checklist

• I searched existing issues and this is not a duplicate.
• I described the problem and desired behavior.

[cv]

Lifecycle integration dependencies

This issue should consume, rather than duplicate, these shared contracts:

• refactor(onboard): complete FSM ownership and lifecycle recovery #7700 for machine-state, recovery, desired-state, and receipt ownership; refactor(onboard): centralize messaging plan authority #7718 is the currently open desired-state authority PR.
• Decompose onboarding into phase composition #7695 / Move sandbox actions into feature-owned application modules #7696 for final onboarding phase composition and feature-owned lifecycle application modules.
• [Epic] Support native Podman with buildless managed onboarding #7744 for buildless managed-image selection and the injected RuntimeProviderBundle; Pi does not need to wait for Podman unless [Pi 1/8] Accept product scope, ownership, threat model, and compatibility matrix #7926 chooses Podman launch scope.
• refactor(agent): derive state handling from definitions #8143 plus the approved refactor(hermes): make NemoClaw the managed gateway lifecycle authority #8010 / refactor(hermes): model durable state and restore order explicitly #8009 stack for manifest-derived state projection, provider-owned mutation, and staged restore.

Expected sequence:

1. Select and persist the Pi AgentDefinition through existing onboarding intent.
2. Resolve the exact Pi managed image through the shared catalog.
3. Build and apply a secret-free startup profile through the existing bootstrap contract.
4. Record generic image/profile/runtime receipts through OnboardRuntime.
5. Delegate connect, status, logs, rebuild, backup/restore, upgrade, recovery, and destroy through feature and provider contracts.

Pi must not add a machine state, direct checkpoint write, compute-runtime identity comparison, or Pi-specific rebuild/snapshot/recovery branch. #7704 health-before-delete remains separate unless the accepted #7926 v1 scope requires it.