Fix NemoHermes first-run onboarding

[ericksoa]

Summary

• make NemoHermes default to a Hermes sandbox name and keep installer next-step output tied to the actual onboard session
• prevent silent same-name cross-agent reuse while preserving side-by-side OpenClaw and Hermes sandboxes under the shared OpenShell gateway
• persist per-sandbox agent metadata/default selection on create and reuse, make Hermes setup failures fatal, and add clearer typo/command-order diagnostics
• show per-sandbox agent type in list output

Validation

• npm run build:cli
• npx vitest run test/install-preflight.test.ts test/cli.test.ts test/onboard.test.ts src/lib/agent-onboard.test.ts src/lib/inventory-commands.test.ts --maxWorkers=1
• npx vitest run test/nemohermes-alias.test.ts
• npx vitest run src/lib/inventory-commands.test.ts src/lib/agent-onboard.test.ts
• git diff --check

Summary by CodeRabbit

• New Features

  • Agent-aware sandbox naming defaults for improved onboarding experience.
  • Agent drift detection prevents reusing sandboxes with different agent types.
  • CLI now suggests corrections for misspelled commands and incorrect argument order.
  • Agent type displayed in sandbox inventory listings.

• Bug Fixes

  • Agent binary verification during onboarding prevents setup with missing executables.
  • Gateway health probe failures now properly fail agent setup instead of only warning.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Changes introduce agent-aware sandbox defaults, preflight verification of agent binary availability, detection and handling of agent drift during sandbox reuse, updated inventory output formatting, and CLI error recovery for command typos and argument ordering issues. The install script's default resolution now prioritizes session-derived names over environment variables with agent-dependent fallbacks.

Changes

Cohort / File(s)	Summary
Agent Verification & Preflight src/lib/agent-onboard.ts, src/lib/agent-onboard.test.ts	Adds sandbox exec-based verification that agent binary exists and is executable before gateway configuration; marks agent setup as failed and terminates on missing binary or persistent gateway health probe timeout.
Sandbox Inventory Display src/lib/inventory-commands.ts, src/lib/inventory-commands.test.ts	Renders agent: <agent> field in sandbox inventory output alongside model, provider, GPU/CPU, and policies; updates test expectations to include agent names in formatted list rows.
Onboarding & Agent Handling src/lib/onboard.ts, test/onboard.test.ts	Introduces agent-aware sandbox naming defaults, agent drift detection at reuse time, conditional sandbox recreation, registry updates with agent metadata, and exported helper functions for sandbox name normalization and default selection.
Install Script & Defaults scripts/install.sh, test/install-preflight.test.ts	Modifies resolve_default_sandbox_name to prioritize session-derived names via onboard-session.json, fallback to environment variable, and use agent-dependent defaults ("hermes" for Hermes agent, "my-assistant" otherwise); adds regression tests for Hermes defaulting and session-state override behavior.
CLI Error Recovery src/nemoclaw.ts, test/cli.test.ts	Adds command-typo detection via edit distance matching with "Did you mean: …" suggestions; detects misplaced sandbox names in connect invocation and prints corrected argument order hints; updates list output tests to expect agent: openclaw field.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 A sandbox with an agent to call,
Names resolved with grace and with thrall,
Drift detected, binaries checked with care,
Typos corrected with helpful flair—
The onboarding dance, now more robust for all!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.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 and specifically describes the main change: fixing NemoHermes first-run onboarding, which aligns with the primary objectives of agent-aware sandbox naming, proper metadata persistence, and setup failure handling.
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.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/nemohermes-first-run

---

_{Review rate limit: 9/10 reviews remaining, refill in 6 minutes.}

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

[ericksoa]

Superseded by #2781. I had to recreate the PR because repository rules block force-pushing the amended DCO-signed commit.