feat(cli): add Hermes ACP adapter over OpenShell SSH

[apurvvkumaria]

Outcome

Adds the packaged host-side nemoclaw-acp executable for connecting an external ACP client to the managed Hermes ACP server over OpenShell SSH. The adapter selects and validates one registered, ready sandbox, preserves duplex ACP streams and remote status, and cleans up the host and remote processes across normal exit, disconnect, cancellation, timeout, and transport failure.

Reason

Raw external invocation of hermes-acp does not own NemoClaw target selection, compatibility validation, lifecycle fencing, signal forwarding, or cleanup. The host-side adapter provides those product guarantees while retaining OpenShell SSH as the single transport.

Related issues

• Part of Decide and qualify Hermes ACP transport over OpenShell #10947

Changes

• Register nemoclaw-acp in the npm package and installer, and remove its managed shims during uninstall.
• Add an ACP-specific typed OpenShell SSH capability that runs only /usr/local/bin/hermes-acp, checks the exact Hermes and ACP versions, uses bounded setup output, and keeps remote standard error out of ACP standard output.
• Validate the gateway, registry generation, live sandbox readiness, and identity under the existing sandbox lifecycle fence through SSH process start; release the fence before waiting for the long-lived session.
• Forward input and output with stream backpressure, propagate cancellation and host signals, preserve remote exit status, terminate the detached SSH process group on failure, and remove the mode-0600 temporary SSH configuration on every result.
• Extend the existing Hermes and rebuild E2E targets for initialization, prompt exchange, remote nonzero exit, cancellation, client disconnect, active OpenShell gateway restart, post-restart reconnect, sandbox rebuild, and process-absence evidence.

Verification

• npm exec -- vitest run --project cli src/lib/acp/command.test.ts src/lib/adapters/openshell/hermes-acp-ssh-cli.test.ts src/lib/actions/uninstall/run-plan.test.ts src/lib/actions/uninstall/run-plan-nvm-leftovers.test.ts — 85 tests passed.
• npm exec -- vitest run --project integration test/install/install-npm-resolution.test.ts test/automation/pull-requests/pr-risk-plan.test.ts — 169 tests passed.
• npm exec -- vitest run --project e2e-support test/e2e/support/hermes-acp-live.test.ts — 4 tests passed.
• npm exec -- vitest run --project package-contract test/package-contract/acp-adapter-packaged.test.ts — passed against the compiled packaged executable.
• npm run typecheck:cli — passed.
• npm run checks:repository — passed, including dependency-pin, architecture, test-registration, and live-assertion ratchets.
• npm run test:e2e-phases:check — passed for 134 tests across 88 live files.
• Normal pre-commit and pre-push hooks — passed.
• GitHub commit verification — both commits are Verified.
• Secret review — the diff contains no secrets, API keys, credentials, authorization headers, or retained ACP payloads.

Review notes

This PR remains draft because #10943 closed without recording the final immutable OpenShell release. The implementation uses the current repository lifecycle contract for OpenShell 0.0.106. Trusted live E2E must pass on the final selected release before this PR is ready and before #10947 can close.

A local broad npm run test:package run passed the new ACP package contract and 1,299 of 1,300 assertions. The unrelated existing migration-state-packaged.test.ts case failed on this macOS host while staging an external OpenClaw-state restore with [Errno 20] Not a directory: var; this PR does not change that migration path.

---

Signed-off-by: Apurv Kumaria akumaria@nvidia.com

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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

[github-actions]

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall line coverage in commit 946b4e9 in the codex/10947-hermes-a... branch remains at 96%, unchanged from commit 281e23e in the main branch.

TypeScript / code-coverage/cli

The overall line coverage in commit 946b4e9 in the codex/10947-hermes-a... branch remains at 83%, unchanged from commit 281e23e in the main branch.

Show a line coverage summary of the most impacted files.

File	main 281e23e	codex/10947-hermes-a... 946b4e9	+/-
src/lib/onboard...w-auto-apply.ts	86%	73%	-13%
src/lib/onboard...ed-lifecycle.ts	77%	75%	-2%
src/lib/onboard...-transaction.ts	70%	69%	-1%
src/lib/actions...ateway-state.ts	78%	80%	+2%
src/lib/onboard...der/registry.ts	93%	95%	+2%
src/lib/onboard...on-authority.ts	82%	88%	+6%
src/lib/onboard...driver-start.ts	51%	58%	+7%
src/lib/inferen...ocal-runtime.ts	87%	97%	+10%
src/lib/acp/command.ts	0%	83%	+83%
src/lib/adapter...-acp-ssh-cli.ts	0%	86%	+86%

---

_{Updated September 09, 2026 06:51 UTC}

[github-actions]

PR Review Advisor finished for commit 946b4e9. Include the Advisor findings in the complete PR feedback collection. Verify and group valid findings before repair.

All previous runs