feat(snapshot): prepare immutable managed clone handoff

[ericksoa]

Summary

Adds the inert, provider-neutral contract for handing a managed snapshot clone to a replacement workload. The plan binds exact source snapshot authority, destination identity, startup profile, inference routes, messaging state, and provider receipt before any later slice may mutate or publish the clone.

This slice intentionally exposes no snapshot-action dependency or production caller. It does not activate clone handling, buildless onboarding, Podman, or any partial runtime support.

Related Issue

Part of #7744

Changes

• Define immutable clone source, destination, provider receipt, and managed-profile handoff contracts.
• Bind clone authority to exact provider, runtime snapshot, source/destination agent, platform, profile, and registry revision.
• Add all-agent startup rebind planning for OpenClaw, Hermes, and LangChain Deep Agents Code.
• Normalize inference-route and messaging credential/host-forward rebinding without runtime-specific central switches.
• Reject stale, mutable, mismatched, cross-agent, malformed, or hostile-provider receipts.
• Freeze provider receipts before provider acceptance so callbacks cannot mutate reviewed authority.
• Prove the contract remains dormant through the public snapshot action: managed cross-sandbox restore exits before destination deletion, provider creation, clone creation, or state restore.
• Document that clone handoff remains deferred to later transactional integration.
• Apply the five still-valid CodeRabbit cleanup findings: canonical sandbox-template resolution, cast-free agent narrowing, shared OpenClaw/Hermes config selection, isolated environment stubbing, and a fully typed messaging-plan fixture.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Exact-head audit covers immutable provider receipts, source/destination authority, credential and inference rebinding, hostile callback mutation, and dormant production boundaries.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: Reviewed the lifecycle-contract update and exact production-boundary diff at head/base 6b6605b76e60197b2407897fd9a31bfa4134b7e0 / 56b26f173a4a3fbed6af77e01f6f3ddda84b237f. The append-only restack preserves the managed-clone review thesis while incorporating the merged fix(security): validate snapshot base64 linearly #8081 sanitizer correction from main. The four-file CodeRabbit cleanup uses existing canonical contracts and completes the test fixture's discriminated types; it changes no user-visible support claim. The internal documentation correctly keeps managed clone handoff deferred and dormant, and behavioral public-restore coverage proves managed clone attempts fail closed before destination deletion, provider creation, clone creation, or state restore. No user-visible buildless or Podman support is activated or advertised, so public support documentation remains intentionally unchanged.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• Exact validated head/base: 6b6605b76e60197b2407897fd9a31bfa4134b7e0 / 56b26f173a4a3fbed6af77e01f6f3ddda84b237f.
• Review budget: 22 files, +2,101/-17.
• Stable patch ID: ca7a91e9d6c5ce1241c0d00d8070113d66916a00.
• All three appended cleanup/restack commits are signed-DCO and GitHub Verified; the exact-head DCO check passes.
• The exact-head tree passes 51 focused clone-contract, messaging-parser, channel-state, and public-boundary tests across five files.
• The exact-head tree passes all 15 snapshot-sanitizer failure tests, including the maximum-size canonical payload and oversized/malformed no-overflow cases from merged fix(security): validate snapshot base64 linearly #8081.
• npm run build:cli, npm run typecheck:cli, npm run checks:repository, normal pre-push TypeScript/version gates, commitlint, Biome, and git diff --check pass.
• Behavioral dormancy coverage proves public managed clone restore exits before every destination effect.
• Hostile-provider coverage proves receipt mutation after callback entry cannot change reviewed authority.
• The exact-head clone-authority test adds zero if statements and its 12 cases pass after linearization.
• No production clone caller, runtime selection change, Podman switch, or public activation exists.
• Applicable broad gate passed — exact-head CI run 30770174361, advisor run 30770173371 attempt 2 (merge_as_is, 0 blockers/warnings/suggestions), CodeRabbit SUCCESS with zero unresolved threads, and protected E2E child run 30770630425 attempt 1 plus coordination run 30770608520 and observer run 30770187080 all passed.
• Exact-head protected-E2E evidence: child run 30770630425 passed all 15 jobs on attempt 1. Coordination run 30770608520 verified the evidence, and coordination check 91555901383 bound PR/head/base 8032:6b6605b76e60197b2407897fd9a31bfa4134b7e0:56b26f173a4a3fbed6af77e01f6f3ddda84b237f; observer run 30770187080 passed.
• Maintainer disposition: CodeRabbit's generic 8.33% docstring-coverage warning is waived for this slice. TypeScript contracts, focused behavioral tests, and lifecycle documentation carry the behavior; boilerplate docstrings are out of scope. This does not claim that warning passed.

Risk Plan

• Primary risk: treating mutable or mismatched clone authority as valid and rebinding secrets/routes/state to the wrong destination.
• Containment: exact immutable authority plus agent, provider, platform, source/destination, registry, profile, inference, and messaging checks fail closed.
• Regression risk: accidental eager imports can alter existing snapshot test mocks before activation. A dedicated dormancy assertion and the previously failing snapshot suites prove the seam is absent here.
• Rollback: one inert contract slice; no production action imports it.

Stack

• Base: merged PR3.8 feat(snapshot): preserve managed runtime authority #8031 plus merged sanitizer correction fix(security): validate snapshot base64 linearly #8081; current main exact head 56b26f173a4a3fbed6af77e01f6f3ddda84b237f.
• This slice: PR3.9A feat(snapshot): prepare immutable managed clone handoff #8032, branch feat/managed-clone-handoff-contract, exact head 6b6605b76e60197b2407897fd9a31bfa4134b7e0.
• Next: PR3.9B feat(snapshot): add managed clone provider transaction #8034 adds the provider transaction/dependency surface while remaining dormant; PR3.9C adds the Hermes-specific broker boundary.
• Buildless and Podman support remain disabled until the full all-agent, multiarch, GPU/local-inference, recovery, installer, and protected-E2E gates in [Epic] Support native Podman with buildless managed onboarding #7744 pass.

Signed-off-by: Aaron Erickson aerickson@nvidia.com

Summary by CodeRabbit

• New Features

  • Added managed workload and startup profile cloning with validation, destination-specific rebinding, and immutable handoff data.
  • Added messaging-plan rebinding that removes source credentials and adapts provider identities.
  • Added clone authorization across runtime providers.
  • Added environment-aware restoration, inference-route resolution, and provider-name validation.
  • Added Hermes destination inference tracking.

• Bug Fixes

  • Prevented unsafe restoration and clone handoffs when validation or authorization fails.
  • Rejected inconsistent messaging channel disablement settings.

• Tests

  • Expanded coverage for cloning, credential isolation, provider rebinding, immutability, and failure scenarios.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.