fix(hermes): explain Desktop version mismatch (Refs #5845)

[deepujain]

Summary

PR #5594 already moved new Hermes sandboxes to Hermes Agent v2026.6.19, which is newer than the first Desktop-compatible backend. This PR covers existing stale Hermes sandboxes: when NemoClaw detects a Hermes backend older than v2026.6.5, it now says why Hermes Desktop will fail and points the user at rebuild.

Changes

• src/lib/sandbox/version.ts: adds a Hermes Desktop compatibility warning for stale Hermes versions that lack /api/profiles/sessions.
• src/lib/actions/sandbox/status.ts: prints that warning next to the existing stale-version rebuild hint.
• src/lib/sandbox/version.test.ts, src/lib/actions/sandbox/status-flow.test.ts, src/lib/actions/sandbox/connect-flow.test.ts: cover helper, status, and connect warning behavior.

Testing

• npm install --ignore-scripts - installed this worktree's locked dependencies; npm reported the existing audit warnings and that local Node v22.12.0 is below the repo's >=22.16.0 engine.
• npm run build:cli - passed.
• HOME=/private/tmp/nemoclaw-5845-vitest-home npx vitest run --project cli src/lib/sandbox/version.test.ts src/lib/actions/sandbox/status-flow.test.ts src/lib/actions/sandbox/connect-flow.test.ts - passed, 30 tests.
• npm run typecheck:cli - passed.
• npm run source-shape:check - passed outside the sandbox after the sandboxed run hit the known tsx IPC pipe EPERM.
• npm run test-size:check - passed outside the sandbox.
• npx @biomejs/biome format src/lib/sandbox/version.ts src/lib/sandbox/version.test.ts src/lib/actions/sandbox/status.ts src/lib/actions/sandbox/status-flow.test.ts src/lib/actions/sandbox/connect-flow.test.ts - passed, no fixes applied.
• npx @biomejs/biome lint src/lib/sandbox/version.ts src/lib/sandbox/version.test.ts src/lib/actions/sandbox/status.ts src/lib/actions/sandbox/status-flow.test.ts src/lib/actions/sandbox/connect-flow.test.ts - passed.
• git diff --check - passed.
• HOME=/private/tmp/nemoclaw-5845-fulltest-home npm test - attempted; timed out after 300s with unrelated local environment-sensitive failures visible in Docker/port/gateway process suites such as test/sandbox-provisioning.test.ts, src/lib/onboard/preflight.test.ts, and test/cli/doctor-gateway-token.test.ts.

Evidence it works

The focused regression tests simulate a Hermes sandbox at 2026.5.16 with a current expected version of 2026.6.19. status now prints that Hermes Desktop requires v2026.6.5+ and that the old backend lacks /api/profiles/sessions; connect prints the same stale-version guidance before attaching.

Refs #5845

Signed-off-by: Deepak Jain deepujain@gmail.com

Summary by CodeRabbit

• New Features

  • Added Hermes Desktop compatibility warnings when a sandbox agent version is out of date.
  • Status and connection flows now show clearer guidance, including update and rebuild instructions.

• Bug Fixes

  • Improved version-staleness messaging for Hermes sandboxes so outdated setups are flagged more explicitly.
  • Added coverage to ensure the warning appears only for the relevant agent and version state.

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9aa5c26e-d1e8-4498-bc62-69cdb99009c6

📥 Commits

Reviewing files that changed from the base of the PR and between c1c7c1d and 79c6223.

📒 Files selected for processing (5)

• src/lib/actions/sandbox/connect-flow.test.ts
• src/lib/actions/sandbox/status-flow.test.ts
• src/lib/actions/sandbox/status.ts
• src/lib/sandbox/version.test.ts
• src/lib/sandbox/version.ts

---

📝 Walkthrough

Walkthrough

Hermes sandbox version checks now emit compatibility guidance when the agent version is stale. The shared warning formatting is updated, and status and connect flows/tests surface the new Hermes-specific output.

Changes

Hermes Desktop compatibility warnings

Layer / File(s)	Summary
Version warning helper src/lib/sandbox/version.ts, src/lib/sandbox/version.test.ts	formatStalenessWarning now appends Hermes Desktop compatibility text, and tests cover stale, current, and non-Hermes cases.
Status warning output src/lib/actions/sandbox/status.ts, src/lib/actions/sandbox/status-flow.test.ts	showSandboxStatus prints Hermes compatibility lines during stale status output, and the status flow test checks the emitted guidance.
Connect flow guidance src/lib/actions/sandbox/connect-flow.test.ts	The connect flow harness accepts version-check inputs and warning lines, and a new test asserts Hermes compatibility guidance appears before connecting.

Sequence Diagram(s)

sequenceDiagram
  participant showSandboxStatus
  participant sandboxVersion
  participant console
  showSandboxStatus->>sandboxVersion: formatHermesDesktopCompatibilityWarning(sandboxName, versionCheck)
  sandboxVersion-->>showSandboxStatus: warning lines
  showSandboxStatus->>console: error(warning lines)

Loading

sequenceDiagram
  participant connectSandbox
  participant sandboxVersion
  participant console
  connectSandbox->>sandboxVersion: checkAgentVersion(...)
  sandboxVersion-->>connectSandbox: versionCheck
  connectSandbox->>sandboxVersion: formatStalenessWarning(...)
  sandboxVersion-->>connectSandbox: warning lines
  connectSandbox->>console: error(warning lines)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• NVIDIA/NemoClaw#5833: Also touches src/lib/actions/sandbox/status.ts and version-check output around showSandboxStatus.

Suggested labels

integration: hermes, area: cli, area: sandbox, bug-fix, v0.0.69

Suggested reviewers

• cv
• jyaunches

Poem

I thumped through the sandbox, so brisk and so spry,
With Hermes warnings that winked by and by.
If versions grow old, I tap my left paw,
Then hop to the guidance: rebuild, check, and straw.
🐇✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: explaining Hermes Desktop version mismatch handling for stale Hermes sandboxes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[wscurran]

✨ Thanks for adding the Hermes Desktop compatibility warning for stale sandboxes older than v2026.6.5. This proposes a way to surface the version mismatch reason and point users at the rebuild command when the backend lacks the required API endpoint.

---

Related open PRs:

• #5594 feat(hermes): bump Hermes Agent to v2026.6.19

---

Related open issues:

• #5845 [macOS][Sandbox] Hermes Desktop app fails to start against NemoClaw sandbox — "Expected JSON from /api/profiles/sessions but got HTML"

[tedy-y]

Issue #5845 disappeared, so I guess we don't really need this fix.