fix(sandbox): scope the agent version probe to the sandbox's gateway

[harjothkhara]

Summary

upgrade-sandboxes --check reported a live Hermes sandbox as Unknown version: <name> v? → v0.18.0. The sandbox listing is scoped to the sandbox's recorded gateway, but the version probe was not: openshell sandbox get and sandbox ssh-config fall back to OpenShell's mutable current selection when no gateway is given, so a sandbox bound to a sibling gateway was looked up on the wrong one, came back "not found", and its version could not be resolved. The probe now targets the sandbox's own recorded gateway, so the check reports the real version.

Related Issue

Refs: #7429

Deliberately not Closes:. This fixes only the version-resolution half of the issue. The policy-remove idempotency failure (issue 1) and the orphan-detection warning are separate code paths and remain open, so auto-closing #7429 on merge would hide unfixed work.

Changes

• src/lib/adapters/openshell/client.ts — captureSandboxSshConfigCommand accepts an optional gatewayName and scopes both the sandbox get and sandbox ssh-config invocations to it. The -g flag is placed after the subcommand pair, matching the existing gatewayScopedArgs helper in actions/sandbox/gateway-state.ts (duplicated rather than imported — an adapter must not depend on the actions layer). Omitting gatewayName preserves today's ambient-selection behavior, so the two existing callers are unchanged.
• src/lib/sandbox/version.ts — probeAgentVersion resolves the sandbox's recorded gateway with the existing resolveSandboxGatewayName and passes it. When that resolver rejects a persisted binding, the probe is skipped entirely and the version is reported unverifiable — it does not fall back to an unscoped query. An entry with no binding fields resolves to the canonical default gateway without throwing, so the rejected case is always genuine corruption, and probing it unscoped would let a same-named sandbox on another gateway be probed and its version cached onto the corrupted row.

No new abstraction, configuration, fallback, or compatibility path. gatewayName is an optional argument on one existing function, consumed by one caller, covered by the tests below.

Behavior note for review: a registry row that pre-dates the per-port migration resolves to the canonical nemoclaw and is now pinned explicitly instead of inheriting OpenShell's current selection. That is the intended correction — resolveSandboxGatewayName is already the designated authority for sandbox-scoped commands — but it does mean such a row now probes nemoclaw rather than whatever gateway happened to be selected.

Type of Change

• Code change (feature, bug fix, or refactor)

Quality Gates

• Tests added or updated for changed behavior
• Docs not applicable — justification: docs/manage-sandboxes/update-sandboxes.mdx and the changelog describe that upgrade-sandboxes probes the live agent version, which is still accurate. No page documents which gateway the probe targets.
• Sensitive paths changed (sandbox)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: maintainer-approved at exact head a826664db8c202fad81d215d1702a0188247e00b; the change scopes two read-only OpenShell lookups and fails closed on invalid bindings without granting new capability.

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: The fix-forward changes only test fixtures for the existing recorded-gateway probe behavior; production behavior and user-facing documentation contracts are unchanged.
• Agent: Codex Desktop

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed
• Targeted behavior tests pass — core probe tests: npx vitest run --project cli src/lib/adapters/openshell/client.test.ts src/lib/sandbox/version.test.ts → 50 passed; fix-forward affected integration tests → 18 passed individually; gateway-recovery regression file → 14 passed
• No secrets, API keys, or credentials committed

Tests

Four tests, each red against origin/main sources and green here (verified by restoring both source files to origin/main and rerunning the new tests: 5 failed → 50 passed):

test	proves
client.test.ts — "scopes both sandbox lookups to the requested gateway"	-g <name> reaches the actual argv of both hops
version.test.ts — "probes the sandbox's own recorded gateway…"	a sandbox on nemoclaw-18080 is probed against that gateway
version.test.ts — "scopes a Hermes sandbox on a non-default gateway…"	the exact reported topology: Hermes agent + nemoclaw-18080 resolves instead of v?
version.test.ts — "does not probe at all when the persisted gateway binding is corrupted"	a rejected binding makes no OpenShell/ssh call and reports unavailable / invalid-gateway-binding

Review follow-ups applied

• PR review advisor PRA-1 — the first revision fell back to an unscoped probe when the binding was rejected, reintroducing the same defect for corrupted rows. Now the probe is skipped outright. Advisor is info_only / 0 findings on the current head.
• CodeRabbit — a skipped probe was still reported as unknown / probe-failed, which the VersionCheckResult contract reserves for a probe that ran and failed. Now reports unavailable / invalid-gateway-binding. Both states already bucket into the "Unknown version" report, so operator-facing output is unchanged.
• Cross-model review — aligned -g placement with the existing gatewayScopedArgs convention, added the Hermes + non-default-gateway test, and changed Closes: to Refs: since only half the issue is fixed.

Real-behavior proof

Harness drives the real path — checkAgentVersion → probeAgentVersion → captureSandboxSshConfigCommand → real spawnSync — with only the two external binaries stubbed at the process boundary (openshell via NEMOCLAW_OPENSHELL_BIN, ssh via PATH). The stub models the reported topology: sandbox hermes-sb exists only on nemoclaw-18080, while ambient selection is the default nemoclaw.

BEFORE (origin/main):

openshell invocations (real subprocess argv):
   openshell sandbox get hermes-sb

verdict:
   detectionMethod    = unknown
   sandboxVersion     = null
   verificationFailed = true

upgrade-sandboxes --check would report:
   Unknown version:  hermes-sb  v? → v0.18.0

AFTER (this branch):

openshell invocations (real subprocess argv):
   openshell sandbox get -g nemoclaw-18080 hermes-sb
   openshell sandbox ssh-config -g nemoclaw-18080 hermes-sb

verdict:
   detectionMethod    = ssh-exec
   sandboxVersion     = 0.18.0
   verificationFailed = false

upgrade-sandboxes --check would report:
   resolved:         hermes-sb  v0.18.0 → v0.18.0

The BEFORE output reproduces the reported symptom verbatim, including v? → v0.18.0.

Blast radius

npx vitest run --project cli src/lib/adapters src/lib/sandbox src/lib/state → 936 passed, 16 failed. All 16 failures are in src/lib/state/state-file-key-merge-behavior.test.ts and state-file-key-merge-file-safety.test.ts, and reproduce identically on pristine origin/main with this change removed — pre-existing, unrelated to this diff. npm run typecheck:cli → 0 errors after npm run build:cli.

Honest limitations

• The reported regression window is not confirmed. The issue attributes this to v0.0.90 → v0.0.91. [DGX Station][CLI&UX] nemoclaw upgrade-sandboxes --check starts a new gateway and strands existing sandboxes #7279 — which made --check target the recorded gateway — landed in v0.0.94, and the v0.0.90…v0.0.91 range contains no change to this path. With Logs: Not captured I could not bisect it. This is submitted as a defect present on current main, not as a bisected regression.
• Only the version-resolution half of [Linux][CLI&UX] hermes runtime-config-guard blocks consecutive policy-remove and upgrade-sandboxes cannot resolve hermes sandbox version #7429 is fixed. The policy-remove idempotency failure needs a live Hermes sandbox to reproduce, which I could not do.
• The orphan line in the report is a separate matter. 1 recorded sandbox(es) were not found on their recorded gateway: hermes renders the sandbox name list, not a gateway name, and [NemoClaw][onboard][All Platforms] nemoclaw uninstall + reinstall flow leaves an orphaned sandbox that the reinstalled CLI can't recover or clean up #6520 already excludes orphans from the unknown-version bucket — so that line concerns a different sandbox (the clone) and is not addressed here. A maintainer should not read this diff as closing that symptom.
• Two sibling call sites share this invariant and are deliberately not changed: getSshConfig (src/lib/state/sandbox.ts, feeding share-command, plugin restore, backup/restore, and the user-managed-files probe) and captureSandboxSshConfig (src/lib/adapters/openshell/runtime.ts, feeding share, skill install/remove, and process recovery). They have the same latent gateway-scoping gap, but I have no repro or proof for those paths and did not want to widen the blast radius. The gatewayName option added here is what they would use. Happy to fold them in, or file a tracking issue, if you'd prefer.
• resolveProbeGatewayName catches broadly. A genuine registry I/O or permission error is currently reported as invalid-gateway-binding, same as a corrupted binding. Separating those needs a typed error from the registry layer; called out rather than expanded into this diff.
• Proof used stubbed openshell/ssh binaries, not live DGX Spark or a real Hermes sandbox. The production code path and argv construction are real; the two external binaries are not.

This PR was assisted by AI but human reviewed along the way.

Signed-off-by: harjoth harjoth.khara@gmail.com

Summary by CodeRabbit

• Bug Fixes
  • Sandbox version checks now reliably scope OpenShell sandbox get and sandbox ssh-config lookups to the sandbox’s configured gateway.
  • Improved reliability for probing sandboxes running on non-default gateways.
  • Corrupted or invalid gateway bindings now fail safely with an unavailable result (invalid-gateway-binding) instead of attempting an SSH probe.

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

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The OpenShell adapter now scopes sandbox SSH lookups to a gateway. Agent version checks resolve persisted gateway bindings, pass valid names to probes, and return an unavailable result without probing when bindings are invalid.

Changes

Gateway-scoped sandbox probing

Layer / File(s)	Summary
OpenShell gateway-scoped SSH configuration src/lib/adapters/openshell/client.ts, src/lib/adapters/openshell/client.test.ts	Adds optional gateway selection to both sandbox get and sandbox ssh-config, with argument assertions covering the scoped calls.
Sandbox version probe gateway resolution src/lib/sandbox/version.ts, src/lib/sandbox/version.test.ts	Resolves persisted gateway bindings, passes valid gateway names into SSH probes, verifies Hermes probing, and returns invalid-gateway-binding without probing when resolution fails.
CLI gateway argument test alignment test/cli/connect-readiness.test.ts, test/cli/connect-recovery.test.ts, test/cli/list-share-live-inference.test.ts	Updates OpenShell command stubs and assertions to include the nemoclaw gateway argument.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: laitingsheng, cv

Sequence Diagram(s)

sequenceDiagram
  participant checkAgentVersion
  participant Registry
  participant captureSandboxSshConfigCommand
  participant OpenShellCLI
  checkAgentVersion->>Registry: Resolve persisted sandbox gateway
  Registry-->>checkAgentVersion: Return gateway name or lookup failure
  checkAgentVersion->>captureSandboxSshConfigCommand: Start scoped SSH probe
  captureSandboxSshConfigCommand->>OpenShellCLI: Run sandbox get and sandbox ssh-config with gateway
  OpenShellCLI-->>captureSandboxSshConfigCommand: Return SSH configuration

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: scoping sandbox agent version probes to the sandbox gateway.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / medium confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

• GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 1 warning · 1 suggestion
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 more warning, 1 more suggestion.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: None

2 optional E2E recommendations

• concurrent-gateway-ports
• upgrade-stale-sandbox

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/sandbox/version.ts`:
- Around line 101-123: Update probeAgentVersion and the public checkAgentVersion
flow so a null result from resolveProbeGatewayName is represented as a dedicated
invalid-binding outcome rather than detectionMethod "unknown" with
unavailableReason "probe-failed". Preserve "unknown"/"probe-failed" only when an
actual probe is attempted and fails, and cover the distinct invalid-binding
result through checkAgentVersion.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: d0ef6b8d-fc6f-4793-8f9f-933367c7edac

📥 Commits

Reviewing files that changed from the base of the PR and between 3bf9ce7 and 74e4e81.

📒 Files selected for processing (4)

• src/lib/adapters/openshell/client.test.ts
• src/lib/adapters/openshell/client.ts
• src/lib/sandbox/version.test.ts
• src/lib/sandbox/version.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• src/lib/adapters/openshell/client.test.ts
• src/lib/adapters/openshell/client.ts
• src/lib/sandbox/version.test.ts

[apurvvkumaria]

Security review: PASS on exact head d8f0aac.

Reviewed all four changed files across the repository's nine security categories. Gateway names are passed as structured argv, persisted bindings are validated by the existing resolver, invalid bindings fail closed without an ambient-gateway probe or cache write, and the diff adds no credential, policy, authorization, dependency, or cryptographic surface.

Verification: targeted CLI tests 50/50 passed; CLI and plugin builds passed; CLI typecheck passed; both commits are DCO-signed and GitHub Verified; the exact head composes cleanly with current main; documentation writer result is no-docs-needed. No blocking findings. Required CI remains mandatory and is not waived.

[apurvvkumaria]

/ok to test d8f0aac

[apurvvkumaria]

Fix-forward pushed in signed, GitHub-verified commit a826664db8c202fad81d215d1702a0188247e00b. The commit updates only the stale integration fixtures/assertions exposed by the gateway-scoped sandbox get / sandbox ssh-config behavior; the contributor's two original commits are unchanged.

Local exact-head evidence:

• connect-readiness.test.ts: 3/3 passed
• connect-recovery.test.ts: 4/4 passed when run alone (the combined-file run showed existing shared-port contention)
• list-share-live-inference.test.ts: 11/11 passed
• gateway-recovery.test.ts: 14/14 passed; the CI timeout is load-sensitive and unrelated
• pre-commit hooks and CLI typecheck passed
• docs-writer re-review: no-docs-needed at a826664db

All fork workflows awaiting approval for this exact head have been approved and are restarting. No release tag change.