Walkthrough

This PR introduces .hermes_history as a persistent agent state file, adds hardened O_NOFOLLOW-based layout repair logic, documents its shields-up exemption, and validates full backup/restore behavior with comprehensive snapshot tests.

Changes

Hermes History Persistence and Repair

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• NVIDIA/NemoClaw#4708: Overlaps on ensure_hermes_history_file hardening in agents/hermes/start.sh and the startup repair behavior for .hermes_history during shields-up lock scenarios.

Suggested labels

integration: hermes, v0.0.58, bug-fix

Poem

🐰 A history file now persists and survives,
With O_NOFOLLOW guards keeping inode safe,
Through shield-ups and backups, the data thrives,
No symlinks shall fool this rabbit's escape! 🔐

❌ Failed checks (1 warning)

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

🛠️ Needs attention

• None.

🔎 Worth checking

• Snapshotting .hermes_history can preserve sensitive prompt contents (agents/hermes/manifest.yaml:98): Adding `.hermes_history` to Hermes durable `state_files` means rebuild snapshots now copy prompt_toolkit history. That history can contain pasted API keys, credentials, private prompts, or other sensitive user input. The existing backup sanitizer strips known credential filenames, `.env` key patterns, and JSON config content, but it does not scrub arbitrary history text.
  • Recommendation: Decide whether preserving prompt history is an intentional privacy tradeoff. If yes, document it in user-facing snapshot/rebuild notes; if not, add an opt-out or sanitizer for `.hermes_history` before writing the backup.
  • Evidence: The manifest adds `- path: .hermes_history`, and `test/snapshot.test.ts` now expects `.hermes_history` to be backed up and restored verbatim as `original history\n`.
• Privileged fd-based history repair branch lacks direct coverage (agents/hermes/start.sh:439): The new repair helper is a sandbox-boundary root path: when the entrypoint runs as root it resolves the sandbox uid/gid and applies `os.fchown(fd, uid, gid)` plus `os.fchmod(fd, mode)` to the opened inode. The nearby unit harness stubs `id -u` to a non-root value and validates symlink, directory, and hardlink refusals, but it does not directly prove the root-only `fchown` branch preserves locked config files or that the post-open inode recheck catches a path swap.
  • Recommendation: Add a focused privileged-path test or identify runtime validation that exercises repair as root against a locked config root, including a malicious hardlink/path-swap-style case where feasible.
  • Evidence: `ensure_hermes_history_file` conditionally calls `os.fchown` only when `os.geteuid() == 0`; existing tests cover unsafe path shapes but the extracted shell harness stubs `id -u` to `1000` and does not force the Python helper through the root branch.

🌱 Nice ideas

• None.

Current findings:

• Snapshotting .hermes_history can preserve sensitive prompt contents (agents/hermes/manifest.yaml:98): Adding `.hermes_history` to Hermes durable `state_files` means rebuild snapshots now copy prompt_toolkit history. That history can contain pasted API keys, credentials, private prompts, or other sensitive user input. The existing backup sanitizer strips known credential filenames, `.env` key patterns, and JSON config content, but it does not scrub arbitrary history text.
  • Recommendation: Decide whether preserving prompt history is an intentional privacy tradeoff. If yes, document it in user-facing snapshot/rebuild notes; if not, add an opt-out or sanitizer for `.hermes_history` before writing the backup.
  • Evidence: The manifest adds `- path: .hermes_history`, and `test/snapshot.test.ts` now expects `.hermes_history` to be backed up and restored verbatim as `original history\n`.
• Privileged fd-based history repair branch lacks direct coverage (agents/hermes/start.sh:439): The new repair helper is a sandbox-boundary root path: when the entrypoint runs as root it resolves the sandbox uid/gid and applies `os.fchown(fd, uid, gid)` plus `os.fchmod(fd, mode)` to the opened inode. The nearby unit harness stubs `id -u` to a non-root value and validates symlink, directory, and hardlink refusals, but it does not directly prove the root-only `fchown` branch preserves locked config files or that the post-open inode recheck catches a path swap.
  • Recommendation: Add a focused privileged-path test or identify runtime validation that exercises repair as root against a locked config root, including a malicious hardlink/path-swap-style case where feasible.
  • Evidence: `ensure_hermes_history_file` conditionally calls `os.fchown` only when `os.geteuid() == 0`; existing tests cover unsafe path shapes but the extracted shell harness stubs `id -u` to `1000` and does not force the Python helper through the root branch.

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• ubuntu-repo-cloud-hermes (high): Runs the typed Hermes scenario with smoke, live cloud inference, and the hermes-specific suite, including runtime.hermes.history-writable. This is the most direct existing E2E for the changed .hermes_history contract under shields down/up and for ensuring the Hermes user flow still starts and serves inference.
• hermes-root-entrypoint-smoke-e2e (medium): Exercises the real Hermes image/start entrypoint and layout repair path. The start.sh Python no-follow fd repair is startup-critical and security-sensitive; this job catches syntax/runtime failures and regressions in Hermes layout repair, gateway health, privilege separation, and config protection.
• rebuild-hermes-e2e (high): Hermes manifest state_files changed to include .hermes_history, which participates in backup/restore during rebuild. This is the closest existing E2E for Hermes rebuild state preservation and credential-exclusion behavior after state contract changes.

Optional E2E

• hermes-onboard-security-posture-e2e (high): Useful additional confidence for Hermes onboard security posture because this PR touches root/sandbox ownership, startup repair, and security-boundary comments, but it does not directly assert the .hermes_history happy path.
• shields-config-e2e (medium): Adjacent coverage for the shared shields up/down lifecycle and immutable config behavior. It is OpenClaw-oriented, so it is optional rather than merge-blocking for a Hermes-specific history carve-out.

New E2E recommendations

• hermes-history-security-negative-paths (high): Existing Hermes history coverage checks the writable happy path, but the start.sh change is specifically a symlink/hard-link/TOCTOU defense. Add an E2E that seeds unsafe .hermes_history shapes under /sandbox/.hermes, runs startup/repair under locked-root conditions, and asserts config.yaml/.env ownership and mode are not downgraded.
  • Suggested test: Add a Hermes locked-root history repair negative E2E for symlink, non-regular file, and hard-link-to-config/.env cases.
• hermes-snapshot-history-durability (high): The manifest now marks .hermes_history as a durable state_file, but the existing live snapshot/rebuild tests do not appear to assert a unique history marker is captured and restored for Hermes.
  • Suggested test: Extend or add a Hermes snapshot/rebuild E2E that writes a unique .hermes_history marker, snapshots or rebuilds, mutates/deletes it, restores, and verifies the marker returns while credentials remain excluded.
• hermes-shields-specific-layout (medium): The shared shields E2E is OpenClaw-centric. Hermes now has a special top-level file that must remain sandbox-writable while the parent config root and config secrets are locked.
  • Suggested test: Add a Hermes shields layout E2E that asserts /sandbox/.hermes root/config/.env lock posture and .hermes_history sandbox:sandbox 0660 writability before and after shields up/down.

Dispatch hint

• Workflow: .github/workflows/e2e-scenarios.yaml
• jobs input: ubuntu-repo-cloud-hermes

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• ubuntu-repo-cloud-hermes: The PR changes Hermes manifest/state-file contract, sandbox policy, Hermes startup layout repair for .hermes_history, shields state-dir locking comments/behavior, and the hermes-specific history-writable scenario script. This scenario is the smallest routed scenario that runs the Hermes cloud onboarding path and includes the hermes-specific suite containing hermes/01-history-writable.sh.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-hermes

Optional scenario E2E

• ubuntu-repo-cloud-hermes-discord: Optional adjacent Hermes onboarding variant. It does not run the hermes-specific history-writable step, but can provide extra coverage that Hermes startup/policy/manifest changes do not regress the Discord messaging profile.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-hermes-discord
• ubuntu-repo-cloud-hermes-slack: Optional adjacent Hermes onboarding variant. It does not run the hermes-specific history-writable step, but can provide extra coverage that Hermes startup/policy/manifest changes do not regress the Slack messaging profile.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-hermes-slack

Relevant changed files

• agents/hermes/manifest.yaml
• agents/hermes/policy-additions.yaml
• agents/hermes/start.sh
• src/lib/shields/state-dir-lock.ts
• test/e2e-scenario/validation_suites/hermes/01-history-writable.sh