feat(snapshot): add Hermes managed clone broker boundary

[ericksoa]

Summary

Adds the dormant Hermes broker boundary needed to stage and later activate provider-owned managed clone rebinding. Broker preparation captures immutable credential, inference-route, messaging, and clone authority; activation consumes only the exact staged plan.

The shared clone/provider contracts remain runtime-neutral. This slice does not wire the production snapshot action, activate buildless onboarding, or advertise Hermes/Podman support.

Related Issue

Part of #7744

Changes

• Add a Hermes managed-clone broker that separates non-destructive staging from later activation.
• Bind staged authority to the exact source snapshot, destination sandbox, provider transaction, Hermes identity, credential plan, messaging plan, and inference routes.
• Resolve the provider through the shared registry contract rather than a Docker/Podman switch.
• Clone and deep-freeze all accepted external authority at the canonical immutable boundary.
• Reject stale, mutated, cross-provider, cross-agent, or mismatched staged plans before activation.
• Keep credentials isolated from logs and persisted public receipts.
• Add focused staging, activation, immutability, and failure-path tests.
• Keep the broker unreachable from the production snapshot action until the later integration slice.

Maintainer Disposition — Advisor PRA-1

PRA-1 is intentionally not implemented in this slice. The epic #7744 activation invariant requires earlier implementation slices to remain inert or internally complete and forbids a partial buildless support path. PR3.9C owns only the Hermes broker preparation and provisioning boundary. A production import or call from the snapshot-clone workflow is therefore prohibited in #8035 because it would cross this review thesis and make the slice product-flow-affecting before the required qualification stack exists.

PR3.15 is the exact owner for production activation after PR3.13A–3.13B and PR3.14A–3.14C are green. That activation slice must invoke prepareHermesManagedCloneBrokerTransaction and provisionHermesManagedCloneBrokerTransaction at the managed snapshot-clone provider-mutation boundary. It must also add a production-call integration test that enters the managed Hermes snapshot-clone workflow and proves staged broker binding, destination-provider creation, and exact binding activation. #8035 must retain its production-call dormancy guard until that activation slice.

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: Internal dormant broker and tests only; no public command, selectable runtime, or support claim changes.
• 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 review covers credential isolation, immutable staged authority, provider/agent binding, and preparation-before-activation ordering.
• 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: no-docs-needed
• Evidence: Independent review confirmed that this patch changes only internal broker/runtime code and focused tests, leaves production snapshot and selectable-runtime behavior unchanged, and needs no user-facing documentation. The exact head/base are f64c4be7765259fd52ef3e9ee916b474e87e7310 / 98a0e0c5d6bb982ad4d0311ce023670acd2a4dfd; the current combined patch remains internal-only at stable patch ID cf7824424540343a477ee292a8bd4c74efa5d7e5.
• Agent: Codex Desktop

DGX Station Hardware Evidence

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

Verification

• Append-only current-main refresh preserves source head 4824fce0edf5de7019fb5b898e8034d68c258d44 and the originally reviewed patch ID 42542f9de3ecdbed69931ad822f7bd954baf3952 as ancestry. Current exact head/base: f64c4be7765259fd52ef3e9ee916b474e87e7310 / 98a0e0c5d6bb982ad4d0311ce023670acd2a4dfd; current raw diff SHA-256 14391a07a0043584abd31fa747100761a53543ed38a353ab277c908d29c37de5, stable patch ID cf7824424540343a477ee292a8bd4c74efa5d7e5, 13-file manifest, and all existing resolved review threads are recorded after the advisor fix.

• Exact locally validated head/base: f64c4be7765259fd52ef3e9ee916b474e87e7310 / 98a0e0c5d6bb982ad4d0311ce023670acd2a4dfd.

• Review budget: 13 files, +2,829/-42.

• Stable combined patch ID: cf7824424540343a477ee292a8bd4c74efa5d7e5.

• The canonical channel-state fixture passed 4/4 and pre-push CLI typecheck passed on the exact head.

• Advisor follow-up removed the host curl dependency from private control-socket calls, replaced the nonexistent recovery-document reference with an inline action, and passed focused broker/runtime tests, CLI build/typecheck, full changed-file hooks, and pre-push.

• The exact-head guardrail follow-up removed redundant manual child cleanup in favor of the owned-resource fixture; 10/10 focused tests, Biome, conditional scanning, commit hooks, and pre-push passed.

• The current advisor follow-up replaces blanket @ts-nocheck in both new Hermes host modules with strict types and verifies their production node --experimental-strip-types load boundary; CLI typecheck and focused broker, credential, and package tests pass.

• Every PR-range commit is SSH-signed, contains a DCO trailer, and is GitHub Verified.

• Focused Hermes broker, runtime credential, policy-boundary, and dormancy suites passed.

• CLI build, CLI typecheck, exact-range pre-commit, commitlint, pre-push, and git diff --check passed.

• Review follow-ups preserve the canonical cloneAndDeepFreeze boundary and harden broker transaction and runtime-credential cleanup.

• No production snapshot caller, runtime-specific central switch, Podman registration, or public activation exists.

• Applicable broad gate passed — exact-head required CI, both advisors, CodeRabbit, and protected E2E are the broad remote gates.

Risk Plan

• Primary risk: exposing credentials or activating a stale/mutated Hermes clone plan against the wrong provider or destination.
• Containment: preparation clones and freezes exact authority; activation revalidates provider, agent, transaction, destination, credential, messaging, and inference bindings.
• Regression risk: new broker construction could leak into current snapshot behavior. The production action remains unwired and focused source-boundary tests cover dormancy.
• Rollback: the 13-file broker slice is independently revertible and not selectable.

Stack

• Base: merged PR3.9B feat(snapshot): add managed clone provider transaction #8034, exact squash commit 98a0e0c5d6bb982ad4d0311ce023670acd2a4dfd on main.
• This slice: PR3.9C, branch feat/hermes-managed-clone-broker, exact head f64c4be7765259fd52ef3e9ee916b474e87e7310.
• Next: PR3.10A defines the dormant transactional bootstrap protocol on this exact parent.
• Buildless and Podman support remain disabled until the complete 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 secure credential handling for managed Hermes clones, including staged activation, rotation, validation, and cleanup.
  • Added broker controls for provider setup, status checks, preflight validation, and lifecycle management.
  • Improved support for multiple sandboxes with isolated provider state and credentials.
  • Added runtime health checks, safe broker reuse, and identity validation.

• Bug Fixes

  • Prevented raw refresh credentials from remaining in runtime environments.
  • Improved rollback and cleanup after provider activation failures.

• Tests

  • Added comprehensive coverage for credential security, broker lifecycle, coexistence, validation, timeouts, and cleanup.

[ericksoa]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[ericksoa]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[ericksoa]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/hermes-tool-gateway-broker.ts (1)

733-799: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Split the broker lifecycle actions into focused helpers.

Line 733 combines credential-free startup, runtime-mismatch handling, credential registration, and broker restart. Extract each refresh-plan action into a helper. Keep ensureHermesToolGatewayBroker as the orchestration point.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/hermes-tool-gateway-broker.ts` around lines 733 - 799, Refactor
ensureHermesToolGatewayBroker into focused helpers for credential-free startup,
runtime-mismatch handling, current-broker credential registration, and broker
start/restart. Keep each helper responsible for its existing branch behavior and
return value, while ensureHermesToolGatewayBroker retains option parsing,
refresh-plan selection, and orchestration through those helpers.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/lib/hermes-tool-gateway-broker.ts`:
- Around line 733-799: Refactor ensureHermesToolGatewayBroker into focused
helpers for credential-free startup, runtime-mismatch handling, current-broker
credential registration, and broker start/restart. Keep each helper responsible
for its existing branch behavior and return value, while
ensureHermesToolGatewayBroker retains option parsing, refresh-plan selection,
and orchestration through those helpers.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 5224de85-4816-44db-ac77-48e5665edb18

📥 Commits

Reviewing files that changed from the base of the PR and between c1fd385 and 9352b77.

📒 Files selected for processing (2)

• src/lib/hermes-tool-gateway-broker.ts
• test/hermes-tool-gateway-broker.test.ts

[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.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-8035.docs.buildwithfern.com/nemoclaw