feat(runtime): persist engine lifecycle and state mutation contract

[ericksoa]

Summary

Adds a dormant, provider-neutral persisted engine lifecycle and exact-runtime state-mutation
contract on top of the managed bootstrap transaction. Snapshot, clone, rebuild, backup, restore,
and recovery bind to durable engine authority. A mandatory supported-or-unsupported
stateMutation facet lets Docker, Podman, and MXC-style providers integrate without central
runtime switches.

This does not activate Podman or change default onboarding. Managed-image onboarding remains
reachable only through the hidden, undocumented --temp-managed-runtime gate. It is inherited
from PR #8261.

Related Issue

Part of #7744.

Changes

• Define versioned lifecycle actions and durable runtime and resource authority.
• Record restart-safe transaction phases, mutation leases, commands, receipts, and retirement
  tombstones.
• Revalidate provider, engine, runtime handles, state digest, and lease during mutation and
  recovery.
• Define a declarative state-mutation plan with bounded selectors and digest bindings.
• Reject executable callbacks, unknown fields, traversal, system roots, control characters,
  duplicate selectors, inherited serialization hooks, and non-scalar Unicode.
• Keep Docker, Kubernetes, Podman, and MXC explicitly unsupported for state mutation in this
  dormant contract slice.
• Normalize Docker create-time attachment and absent port-binding defaults without ignoring
  active TTY, stdin, or port-binding configuration.
• Stage the managed bootstrap request through a root-owned mode-0400 ustar stream so the stopped
  replacement authenticates the envelope independently of the host caller's numeric UID.
• Exercise the real stopped-container create -> copy -> start path with the native managed
  bootstrap as PID 1 for every shipped managed-image agent.
• Resolve same-repository PR identity through the GitHub REST API in the protected E2E
  maintainer procedure.
• Repair the existing stacked merge's omitted onboarding dependencies, duplicate catalog field,
  provider surfaces, test fixtures, and source-shape inventory.
• Add focused lifecycle, adversarial validation, Podman-dormancy, MXC-pluggability,
  Docker-normalization, bootstrap-staging, PID-1, and source-shape coverage.

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 advisor publisher run 31288351290 reported info_only with 0 blockers, 0 warnings, and 0 suggestions.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval
  link, and follow-up issue: The exact-head Terra and Nemotron raw lanes omitted the required
  scope-risk-map analysis protocol; the publisher succeeded with an empty finding ledger, so
  there is no source finding to remediate.

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: Reviewed .agents/skills/_shared/controlled-words.md, .agents/skills/nemoclaw-maintainer-e2e/SKILL.md, docs/security/hermes-0.19.0-dependency-review.md, docs/security/openclaw-2026.7.1-dependency-review.md, and tools/mcp-tool-discovery-runtime/dependency-review.md at commit under review 37bfd3bb3. The text matches the offline Hermes wheel overlay, offline OpenClaw package materialization, reviewed MCP bundle boundary, and PR identity checks. npm run docs completed with 0 errors and 2 Fern upgrade warnings. No blocking documentation finding remains.
• Agent: Codex Desktop

DGX Station Hardware Evidence

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

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in
  GitHub — commit 37bfd3bb3 is signed and GitHub reports valid verification
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr
  passed after refreshing origin/main when hooks were skipped or unavailable — commit
  37bfd3bb3 passed the local commit and pre-push hook path.
• Targeted behavior tests pass for the current change set, or tests are marked not applicable
  above — merge commit 37bfd3bb3: 19/19 focused tests, npm run typecheck:cli,
  npm run checks:repository, the live installer-hash verifier, commit hooks, and
  npm run docs passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes;
  npm run check for repo-wide validation/coverage changes — command/result: all five required
  exact-head contexts, all eight CLI shards, all three direct managed startups, and the real
  all-agent activation passed on 37bfd3bb3.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the
  style guide
  (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

Commit under review: 37bfd3bb348053123980476e23af5e8d667580ef.
Exact public delta: 206 files, +12,839/-597.

---

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

Summary by CodeRabbit

• New Features

  • Improved managed bootstrap delivery during container replacement with safer archive-based transfer.
  • Added stronger validation, leasing, recovery, and retirement support for persisted runtime lifecycle operations.
  • Added foundational planning for runtime state changes; provider execution remains unavailable pending validation.
  • Standardized managed-image runtime identities and improved cross-architecture activation support.

• Bug Fixes

  • Prevented Docker attachment settings from triggering unnecessary launch changes.
  • Normalized empty port bindings and Docker-default tmpfs options.
  • Improved readiness checks and journal recovery during container replacement.

• Tests

  • Expanded lifecycle, bootstrap, archive, state-plan, and activation coverage.

Advisor finding disposition

The raw second-opinion artifact identified a real offline-boundary regression. Protected run
31222691941 then exposed the decisive trusted-workflow boundary: the protected job executes its
build helper from trusted main, so candidate-only seed-overlay helper changes cannot supply the
OpenClaw archive graph before merge. Exact head removes that dependency from the candidate source
itself. The Dockerfile checksum-addresses the complete lock-selected archive set outside RUN,
selects the amd64 or arm64 native subset, verifies every archive against the committed lockfile
SHA-512 identity, and executes npm ci with networking disabled. Imported build cache remains an
optimization, not an input required for correctness; a missing or mismatched locked archive fails
closed instead of falling back to the registry.

The exact-head Terra warning to remove or connect the currently unconsumed persisted-lifecycle and
state-mutation subsystems is intentionally resolved by the binding dormant-slice boundary in
#7744, not by changing this PR into an activation slice:

• [Epic] Support native Podman with buildless managed onboarding #7744 requires earlier provider slices to remain inert or internally complete and forbids a
  partial support claim.
• This PR defines the mandatory supported-or-unsupported provider facet and keeps every current
  provider explicitly unsupported; no production registry or central orchestration path calls it.
• The epic assigns real Docker and Podman stateMutation consumers, durable fencing, interruption,
  and recovery evidence to the later provider execution and activation batches.
• Connecting a production consumer here would violate this review thesis and the activation gate;
  deleting the contract would discard the provider-neutral/MXC-pluggable seam required by the same
  epic.

The dormant source boundary is therefore intentional acceptance evidence for this slice. The later
activation batch remains blocked until named production consumers and protected recovery evidence
exist.

[cv]

Don't add tools/mcp-tool-discovery-runtime/mcp-runtime-npm-cache-seed/*.tgz to the repo

[ericksoa]

Exact-head handoff for 37bfd3bb348053123980476e23af5e8d667580ef:

• Synchronized current main at 290eb94884eb29bc8aac89685e18525bb1292ed3. The two conflict resolutions preserve main's Node-tar scanner removal and retain this PR's locked-cache materializer.
• The requested tools/mcp-tool-discovery-runtime/mcp-runtime-npm-cache-seed/*.tgz files are absent; that directory contains only .gitkeep.
• All five required contexts are green: checks, commit-lint, dco-check, check-hash, and changes.
• GitHub reports the commit verified and the PR mergeable. The documentation receipt passes, and all 11 review threads are resolved.
• The advisor publisher reports 0 blockers, 0 warnings, 0 suggestions, and no follow-up needed. Its two non-required model lanes returned no analysis and failed only their output protocol.

The remaining merge-policy gate is one current human approval. reviewDecision still reflects the older changes-requested review at 054b714, whose literal cache-file request is addressed on this head. Ready for current-head human review.