fix(hermes): preserve home channels across rebuilds

[sandl99]

Summary

Hermes rebuilds previously regenerated .env without retaining home-channel routing written by /sethome.
This change preserves the approved home-channel assignments across rebuild while continuing to regenerate credentials and all other environment values.

Related Issue

Fixes #7803

Changes

• Add a Hermes preserved-environment inventory for *_HOME_CHANNEL, *_HOME_CHANNEL_NAME, and *_HOME_CHANNEL_THREAD_ID.
  The Hermes rebuild flow needs a selective migration because copying the complete .env would also copy credentials.
  src/lib/state/preserved-env/index.test.ts protects wildcard matching, validation, precedence, and inactive-channel behavior.
• Capture allowlisted assignments in the rebuild manifest, then finalize and rebuild the already-preflighted retained image context before deleting the old sandbox.
  The finalized context is fingerprinted again, and current generated assignments remain authoritative when the same key exists.
  Snapshot, Dockerfile-patch, retained-image, and rebuild-flow tests protect capture, image encoding, pre-delete validation, recreate handoff, and disposable-image cleanup.
• Document only the user-facing /sethome rebuild-persistence contract.

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: The implementation review confirmed that the anchored inventory excludes credential keys, rejects duplicate or malformed assignments, remains scoped to Hermes rebuild, and finalizes the retained image before deleting the live sandbox.
• 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: PASS at a2883aa1f; reviewed the writing rules and documentation style for docs/manage-sandboxes/messaging-channels.mdx. The final PR documentation adds only the Hermes /sethome rebuild-persistence contract. Source and focused tests confirm the claim, and generated Hermes and OpenClaw variants render with the correct agent scope. npm run docs:sync-agent-variants, npx vitest run test/changelog-docs.test.ts (6/6), npm run docs (0 errors; 2 known unrelated warnings), and git diff --check passed.
• Agent: Codex CLI — Hermes home-channel routing across rebuilds

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
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: live Hermes rebuild preserved the Slack home channel and thread ID; after the final main merge, npx vitest run --project cli src/lib/actions/sandbox/rebuild-flow.test.ts passed 111/111; npm run build:cli, git diff --check, and normal pre-commit, commit-msg, and pre-push hooks passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• 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)

---

Signed-off-by: San Dang sdang@nvidia.com

Summary by CodeRabbit

• New Features
  • Hermes sandbox rebuilds now preserve configured home-channel routing (*_HOME_CHANNEL*) during backup/restore.
  • Rebuilds merge preserved routing and regenerate all other Hermes configuration automatically.
• Documentation
  • Updated Hermes guidance for safe restore/rebuild behavior and home-channel setup, including using /sethome instead of editing generated files.
• Bug Fixes
  • Preserved routing is validated and applied with correct precedence when regenerating images (preserved values are overridden only when a new assignment is generated).
• Tests
  • Added coverage for home-channel snapshot preservation and preserved environment inventory/merge behavior.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Hermes backups now capture allowlisted home-channel assignments and validate them in rebuild manifests. Recreate flows merge those assignments into the Hermes messaging plan, while documentation describes /sethome, generated-value precedence, and snapshot exclusions.

Changes

Hermes home-channel preservation

Layer / File(s)	Summary
Preserved environment contract src/lib/state/preserved-env/*	Defines the Hermes allowlist, validates .env assignments, and prepends preserved values to compatible rebuild renders.
Hermes backup capture src/lib/state/sandbox.ts, test/hermes-home-channel-snapshot.test.ts	Captures allowlisted assignments over SSH, records them in Hermes manifests, propagates transport failures, and verifies secrets are excluded.
Rebuild and Dockerfile integration src/lib/actions/sandbox/rebuild-recreate-phase.ts, src/lib/actions/sandbox/rebuild-recreate-observability.test.ts, src/lib/onboard/dockerfile-patch.*	Merges preserved assignments during recreation, writes the resulting plan for onboarding, and verifies the preserved render handoff.
Manifest and operator guidance agents/hermes/manifest.yaml, docs/manage-sandboxes/*.mdx	Documents preserved routing assignments, /sethome, rebuild precedence, and excluded generated files.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested labels: integration: hermes, bug-fix

Suggested reviewers: cv

Sequence Diagram(s)

sequenceDiagram
  participant HermesSandbox
  participant BackupState
  participant RebuildPhase
  participant MessagingSetup
  HermesSandbox->>BackupState: capture allowlisted home-channel assignments
  BackupState->>RebuildPhase: provide preservedEnv manifest entries
  RebuildPhase->>MessagingSetup: write merged messaging plan
  MessagingSetup->>HermesSandbox: apply preserved home-channel env-lines

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The rebuild flow, backup capture, and tests now preserve Hermes home-channel assignments, addressing the Slack home channel restore regression.
Out of Scope Changes check	✅ Passed	The changes stay focused on Hermes rebuild preservation, validation, tests, and docs; no unrelated scope is apparent.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preserving Hermes home channels across rebuilds.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/hermes-home-channel-rebuild-7803

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 52461d0 in the fix/hermes-home-chan... branch remains at 96%, unchanged from commit c614c0d in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 52461d0 in the fix/hermes-home-chan... branch remains at 81%, unchanged from commit c614c0d in the main branch.

Show a code coverage summary of the most impacted files.

File	main c614c0d	fix/hermes-home-chan... 52461d0	+/-
src/lib/onboard...shboard-port.ts	96%	90%	-6%
src/lib/platform.ts	89%	84%	-5%
src/lib/actions...flight-phase.ts	99%	96%	-3%
src/lib/actions...ild-pipeline.ts	100%	99%	-1%
src/lib/inferen...ompatibility.ts	94%	95%	+1%
src/lib/onboard...erfile-patch.ts	93%	95%	+2%
src/lib/state/sandbox.ts	81%	85%	+4%
src/lib/domain/.../connect-env.ts	89%	97%	+8%
src/lib/messagi...etup-applier.ts	68%	78%	+10%
src/lib/state/p...ed-env/index.ts	0%	97%	+97%

---

_{Updated August 03, 2026 12:57 UTC}

[github-actions]

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

[coderabbitai]

Actionable comments posted: 2

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

Inline comments:
In `@docs/manage-sandboxes/backup-restore.mdx`:
- Around line 146-153: Reword the sentence in the AgentOnly Hermes guidance from
“A current generated assignment overrides…” to “A newly generated assignment
overrides…” in docs/manage-sandboxes/backup-restore.mdx lines 146-153 and
docs/manage-sandboxes/workspace-files.mdx lines 124-149, preserving the rest of
both sections unchanged.

In `@src/lib/state/preserved-env/index.test.ts`:
- Around line 113-158: Remove the conditional throw in the test at
src/lib/state/preserved-env/index.test.ts lines 113-158 by using a
non-conditional assertion or typed helper to narrow currentRender to an
env-lines render. Also replace the planArg conditional throw in
src/lib/onboard/dockerfile-patch-preserved-env.test.ts lines 111-124 with a
non-conditional defined assertion and safe narrowing; both tests must retain
their existing validation while adding no if statements.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 0c53483c-0669-4427-be45-0e9396940bf8

📥 Commits

Reviewing files that changed from the base of the PR and between eeab81c and 5a87ea6.

📒 Files selected for processing (13)

• agents/hermes/manifest.yaml
• docs/manage-sandboxes/backup-restore.mdx
• docs/manage-sandboxes/messaging-channels.mdx
• docs/manage-sandboxes/workspace-files.mdx
• src/lib/actions/sandbox/rebuild-recreate-observability.test.ts
• src/lib/actions/sandbox/rebuild-recreate-phase.ts
• src/lib/onboard/dockerfile-patch-preserved-env.test.ts
• src/lib/onboard/dockerfile-patch.test.ts
• src/lib/onboard/dockerfile-patch.ts
• src/lib/state/preserved-env/index.test.ts
• src/lib/state/preserved-env/index.ts
• src/lib/state/sandbox.ts
• test/hermes-home-channel-snapshot.test.ts

💤 Files with no reviewable changes (1)

• src/lib/onboard/dockerfile-patch.test.ts

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized terminology decisions differ; normalized E2E selections differ; severity counts match.

4 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• home channel at docs/manage-sandboxes/messaging-channels.mdx:64: primary classified it as define; the second opinion classified it as justified.
• preserved environment at src/lib/state/preserved-env/index.ts:54: selected only by the second-opinion lane as justified.
• preserved-environment inventory at src/lib/state/preserved-env/index.test.ts:56: selected only by the second-opinion lane as justified.
• rebuild-preserved at src/lib/onboard/machine/core-flow-phases.test.ts:366: selected only by the second-opinion lane as justified.

5 additional E2E selections from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

• ubuntu-repo-cloud-openclaw: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• ubuntu-repo-docker-post-reboot-recovery: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• hermes-slack: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• rebuild-hermes-stale-base: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• snapshot-commands: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

1 semantic terminology decision

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• define — home channel at docs/manage-sandboxes/messaging-channels.mdx:64: Retain the /sethome reference as the term definition.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-onboard, full-e2e, hermes-e2e, security-posture, onboard-repair, onboard-resume, rebuild-openclaw, state-backup-restore

1 optional E2E recommendation

• rebuild-hermes

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[cjagwani]

Maintainer security review — exact head 598d45a99809cec0565c4b34f4a011254d1a489a against base 41d8d55f9f0632a69e07cbc172963543fe01bff1: PASS. No security findings.

1. Secrets and credentials — PASS. Capture is limited to exact *_HOME_CHANNEL, *_HOME_CHANNEL_NAME, and *_HOME_CHANNEL_THREAD_ID suffixes. Credential keys such as SLACK_BOT_TOKEN are rejected at capture, manifest-validation, and merge boundaries.
2. Input validation and sanitization — PASS. The parser bounds source and assignment sizes, rejects duplicates and control characters, validates keys and the single .env inventory path, and rejects newline injection and unrecognized assignments.
3. Authentication and authorization — PASS. No auth provider, token, pairing, role, or permission behavior changes. Preserved data is non-secret routing metadata.
4. Dependencies and third-party code — PASS. No dependency, lockfile, registry, image-source, or license change.
5. Error handling and logging — PASS. Capture and validation failures fail the backup/rebuild safely; logs report paths and counts without values. A finalization failure leaves the existing sandbox untouched.
6. Cryptography and data protection — PASS / not applicable. No cryptographic behavior changes. The preserved plan is canonical JSON encoded as base64 and remains inside the existing rebuild artifact boundary.
7. Configuration and infrastructure — PASS. Current manifest renders override preserved values; inactive/non-Hermes plans do not receive the preserved render; the staged Dockerfile is re-fingerprinted after finalization.
8. Security testing — PASS. Tests cover secret exclusion, duplicate and malformed assignments, newline injection, precedence, inactive channels, image finalization, pre-delete validation, snapshot capture, and rebuild handoff. Focused validation passed 151 tests; plugin build and git diff --check passed.
9. Holistic security posture — PASS. The replacement image is finalized and verified before sandbox deletion, preserving the existing fail-closed destructive boundary. No network-policy, capability, filesystem-permission, SSRF, or credential-isolation boundary is weakened.

Files reviewed: all 28 changed files, with deep review of src/lib/state/preserved-env/index.ts, src/lib/state/sandbox.ts, src/lib/actions/sandbox/rebuild-custom-image-preflight.ts, src/lib/actions/sandbox/rebuild-pipeline.ts, src/lib/actions/sandbox/rebuild-recreate-phase.ts, src/lib/onboard/dockerfile-patch.ts, and their focused tests and documentation.

[cjagwani]

Exact-head review remains approved at b51b5271d1a29af6c745f53b72df4d476072853b, but the PR is still based on d52d4599a18490e7f8efc6e8062296fffcbea4a7 while current main is 376beb50b6d184675283bdbc4f2eca18d7200a86. Maintainer edits are disabled, so the merge gate needs an author refresh before current-base CI/E2E evidence can be accepted. I will re-gate the next quiet revision. This is a plain handoff comment, not Changes Requested.

[cjagwani]

Correction to my prior handoff: conflict-free base refreshes are explicitly waived. Please do not merge main solely for base currency; preserving exact-head CI/E2E and documentation receipts is preferred unless GitHub reports a real conflict or reviewed behavior requires a change. The existing approval/review evidence remains in force, and I will continue monitoring mergeability. This is a plain coordination comment, not Changes Requested.

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

[cjagwani]

Exact-head follow-up for 05c866c915e866914cffcffcc46df5eb3c29f95a: the prior approval is stale after the automated conflict-resolution commit. The current revision has only CodeQL results attached and is missing the six required exact-head checks (checks, check-hash, changes, commit-lint, dco-check, and E2E / PR Gate). Holding approval until a fresh current-revision CI/E2E cycle completes. This is a comment only; no Changes Requested state submitted.

[cjagwani]

Exact-head babysitting update for 05c866c915e866914cffcffcc46df5eb3c29f95a (plain comment; no Changes Requested review): I approved the held ordinary workflows, the transient Fern ECONNRESET passed on retry, and all current PR CI, DCO, hash, CodeQL, WSL, macOS, docs, and CLI checks are now green. The bot merge had one conflict in rebuild-pipeline.ts; its resolution correctly retains both the previously approved Hermes prepared-image finalization and current-main route revalidation at the pre-delete boundary.

The deterministic gate is now blocked only because E2E / PR Gate is absent. Completion of substantive run 30571766680 did not attach either the native gate or coordination check, so there is no exact-head E2E verdict to review. Please use the repository-supported fresh controller/backfill path for this unchanged head/base. I am not requesting another branch refresh solely for base currency; GitHub reports the head MERGEABLE.

Superseded by current head 05c866c; exact-head follow-up is waiting on required E2E backfill. No Changes Requested review is being submitted.

[cjagwani]

Reviewed exact head 52461d055727e241f5fb274a6a5f6af15ec1a151. Product scope is established by accepted regression #7803. Required CI, E2E, DCO, commit verification, and automated review gates are green. Security review is clean: preservation is restricted to validated Hermes home-channel keys, credential assignments are excluded, and the retained image context is revalidated before deletion.

[cjagwani]

Post-merge maintainer audit for head 52461d055727e241f5fb274a6a5f6af15ec1a151: this PR was merged by prekshivyas at 2026-08-03T15:57:43Z, before this correction could take effect. My approval had been submitted before the deterministic current-base gate completed: its successful required checks were bound to base c614c0d954126fd6a12ffbe592d8573db81cb646, while main had advanced. REST and GraphQL dismissal calls returned the review unchanged. The code/security review itself was clean and no Changes Requested review was submitted, but the approval should not be treated as evidence that the repository current-base gate was satisfied at merge time.