refactor(acp): recover live gateway before enforcing cached lifecycle state
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 715
Description
## Problem
The Hermes ACP connection path uses the host-side gateway registry as an authority before it recovers and queries the live OpenShell gateway. That ordering makes cached lifecycle observations a prerequisite for reaching the system that owns the live state.
The registry compatibility check currently includes the agent version, OpenShell version, NemoClaw version, lifecycle generation, live identity fingerprint, gateway association, and state root. Some bootstrap information is necessary while a gateway is unavailable, but cached runtime identity and lifecycle observations should not independently decide whether recovery is allowed.
This became visible during the `fa3e36f5f350d8c1d61fc48bc9b1573707694b99` main E2E incident:
- Push run: https://github.com/NVIDIA/NemoClaw/actions/runs/34788709180
- Repeated Hermes job: https://github.com/NVIDIA/NemoClaw/actions/runs/34788709180/job/103823368458
- Related refactor: #11163
The test intentionally stopped the OpenShell gateway and invoked `nemoclaw-acp`. The adapter did not initialize or create a remote process or session, and the gateway remained unavailable until test cleanup restarted it. The repeated attempt reproduced the failure.
The immediate incident also exposed a narrower observer-classification bug: a stopped gateway can return `Connection refused` without repeating its active gateway name. That should be repaired independently. This issue tracks the architectural follow-on rather than weakening or removing the recovery E2E.
## Desired ownership model
- Keep only the minimum local bootstrap information required to identify and start the named gateway.
- Recover the selected gateway before requiring live sandbox identity confirmation.
- Read sandbox identity, configuration, policy, providers, and attachments from live OpenShell after recovery.
- Treat cached lifecycle generation and identity fingerprints as continuity evidence, not a second source of truth.
- Reject a concrete post-recovery identity conflict, but do not reject merely because live confirmation was unavailable while the gateway was down.
- Preserve exact gateway targeting, lifecycle locking, path safety, credential boundaries, and fail-closed behavior for ambiguous or conflicting identities.
## Acceptance criteria
- `nemoclaw-acp --sandbox --gateway ` can recover a stopped, registered gateway using only the minimal trusted bootstrap record.
- Recovery revalidates the sandbox against live OpenShell before starting the ACP transport.
- Stale or conflicting post-recovery identity is rejected with bounded, sanitized diagnostics.
- Host state no longer duplicates live MCP configuration, enforcement state, provider attachments, or other OpenShell-owned runtime truth.
- Unit tests distinguish unavailable pre-recovery state from authoritative post-recovery conflict.
- The existing Hermes ACP gateway-recovery E2E remains strict and passes without a test-side manual restart, additional sleeps, or relaxed assertions.
- Documentation identifies which local fields are bootstrap authority, continuity evidence, or live OpenShell-owned state.
Contributor guide
Research direction
Start with the nemoclaw-acp --sandbox --gateway entry point and the existing Hermes ACP gateway-recovery E2E. Trace the host-side gateway registry checks through recovery, then verify that live OpenShell state is authoritative after recovery and that the strict E2E passes without manual restart, extra sleeps, or relaxed assertions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend, infrastructure, security
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100