fix(status): report SSH-session count instead of a misleading Connected field

[Dongni-Yang]

Summary

nemoclaw status and nemoclaw list printed a Connected: field that was derived only from the local interactive SSH-session count (ps | grep ssh), not from gateway or messaging health. A healthy foreground-managed gateway with a live Slack path but no open SSH session therefore showed Connected: no, and consumers that trust the summary classified an active agent as offline. This renames the field to SSH sessions: (reporting the count, or none) so it names what it actually measures, and drops the redundant, identically-misleading connected boolean from nemoclaw list --json.

Related Issue

Closes #7805

Scope note. This resolves the reported defect by removing the misleading signal: the Connected: line and the nemoclaw list --json connected boolean no longer report SSH-session presence as connection state, so an active agent is never misclassified as offline. It does not add a positive "effective managed Gateway and messaging state" indicator (the other half of the Expected Result); the genuine gateway diagnostic already exists as the gateway: down [state] (reason) line that nemoclaw status prints and exits 1 on. If you want the affirmative gateway/messaging readout, please reopen and we'll scope it as a follow-on.

Changes

• Rename the Connected: line to SSH sessions: in nemoclaw status (status-text.ts) and nemoclaw list (inventory/index.ts); it reports the active SSH-session count, or none. SSH session(s) is the term already used by nemoclaw connect and the command docs.
• Remove the redundant connected boolean from the nemoclaw list --json row and the SandboxInventoryRow type. It was derived from activeSessionCount, which already carries the honest value; the ● list marker now reads activeSessionCount directly (threshold > 0 unchanged, so marker behavior is identical). This is a small --json contract change (a redundant field is dropped, not added).
• Update docs/reference/commands.mdx (and the regenerated agent-variant mirrors) for the renamed field.
• Add a regression test (status-flow.test.ts, #7805): a sandbox with zero SSH sessions renders SSH sessions: none and never connection-negative language.

The genuine gateway-connectivity signal (the doctor checks and the gateway: down exit-1 diagnostic) is intentionally unchanged.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: Updated docs/reference/commands.mdx documents the activeSessionCount integer-or-null contract, removal of connected, and exact SSH-session text behavior. All three generated agent variants contain the corrected contract. Focused tests pass 91/91, and npm run docs passes with 0 errors and two existing warnings.
• 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, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set — three focused status/inventory files pass 91/91; CLI and plugin builds, CLI typecheck, agent-variant sync, and git diff --check pass.
• Applicable broad gate passed — not run; targeted tests cover this display/inventory change
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without errors (doc changes only; two existing Fern warnings)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only) — no new pages

---

Signed-off-by: Dongni Yang dongniy@nvidia.com
Signed-off-by: Charan Jagwani cjagwani@nvidia.com

Summary by CodeRabbit

• Improvements
  • Updated sandbox status and inventory displays to show active SSH activity as SSH sessions: <count> (or SSH sessions: none) for both per-sandbox and global views.
  • Status output now omits SSH-session lines when session probing is unavailable.
  • Updated listing output to use numeric activeSessionCount instead of a connected boolean.
• Documentation
  • Revised the command reference to match the new SSH session reporting wording and refined recovery verification guidance for OpenClaw/OpenShell behavior.

[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 CLI now reports active SSH session counts instead of derived connection states. Inventory data exposes activeSessionCount, status output uses SSH sessions: <count> or none, unavailable probes omit the field, and tests and documentation reflect the updated contract.

Changes

SSH session reporting

Layer / File(s)	Summary
Inventory contract and command rendering src/lib/inventory/index.ts, src/lib/inventory/index.test.ts, test/cli/list-inference.test.ts, docs/reference/commands.mdx	Inventory rows now expose activeSessionCount; list and status output render labeled SSH session counts, while tests and command reference documentation use the updated wording. OpenClaw recovery documentation now describes gateway and host-forward verification.
Sandbox status session output src/lib/actions/sandbox/status-text.ts, src/lib/actions/sandbox/status-flow.test.ts	Sandbox status renders numeric SSH session counts or none, with coverage for populated, empty, and unavailable session probes.

Estimated code review effort: 2 (Simple) | ~15 minutes

Suggested labels: area: sandbox, area: docs

Suggested reviewers: cjagwani, cv, disturbedsage5840c, jyaunches

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 and concisely describes replacing the misleading Connected field with an SSH-session count.

✨ 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/7805-status-ssh-sessions-label

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit d269872 in the fix/7805-status-ssh-... branch remains at 96%, unchanged from commit 77ebb5b in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit d269872 in the fix/7805-status-ssh-... branch remains at 81%, unchanged from commit b5aaa27 in the main branch.

Show a code coverage summary of the most impacted files.

File	main b5aaa27	fix/7805-status-ssh-... d269872	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/platform.ts	89%	84%	-5%
src/lib/core/json-types.ts	100%	100%	0%
src/lib/inventory/index.ts	90%	90%	0%
src/lib/messagi...nnels/policy.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	88%	88%	0%
src/lib/state/config-io.ts	93%	93%	0%
src/lib/tunnel/services.ts	75%	75%	0%
src/lib/actions.../status-text.ts	41%	42%	+1%

---

_{Updated August 01, 2026 12:30 UTC}

[github-actions]

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

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

6 additional E2E selections from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

• sandbox-operations: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• ubuntu-repo-docker-post-reboot-recovery: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• ubuntu-repo-cloud-openclaw: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• sandbox-survival: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• state-backup-restore: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• full-e2e: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

Second-opinion E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

E2E guidance

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

Recommended E2E: onboard-repair, onboard-resume

1 optional E2E recommendation

• sessions-agents-cli

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: 2

🤖 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 `@docs/reference/commands.mdx`:
- Line 1372: Update the `SSH sessions` documentation to state that the line is
emitted only when the active-session probe is available; when OpenShell or
session detection is unavailable, the line is omitted rather than reporting
`none`.

In `@src/lib/inventory/index.ts`:
- Around line 347-355: The list renderer in src/lib/inventory/index.ts lines
347-355 should preserve the existing session dot while emitting “SSH sessions:
<count|none>” for non-null activeSessionCount, using “none” for zero and
omitting the field when the probe is unavailable. Update
docs/reference/commands.mdx line 3084 to document this count-or-none output and
omission behavior; ensure the shared list rendering is authoritative for all
in-scope entrypoints.

🪄 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: 2ac85957-1284-4981-80bf-62fff8f6983f

📥 Commits

Reviewing files that changed from the base of the PR and between eeab81c and a2d56b2.

📒 Files selected for processing (6)

• docs/reference/commands.mdx
• src/lib/actions/sandbox/status-flow.test.ts
• src/lib/actions/sandbox/status-text.ts
• src/lib/inventory/index.test.ts
• src/lib/inventory/index.ts
• test/cli/list-inference.test.ts

💤 Files with no reviewable changes (1)

• test/cli/list-inference.test.ts

[Dongni-Yang]

Thanks @coderabbitai — resolutions below.

Finding 1 (docs, commands.mdx:1372) — addressed in f4e32b5. Both SSH sessions doc lines now state the line is omitted when the session probe is unavailable (rather than reporting none).

Finding 2 (list renderer, index.ts:347-355) — respectfully dismissing (misattribution). The cited doc line commands.mdx:3084 sits under the ### nemoclaw status section, which renders via showStatusCommand and does emit the labeled SSH sessions: <count|none> line (src/lib/inventory/index.ts:548) — so the doc matches. nemoclaw list (renderSandboxInventoryText) intentionally shows the compact ● marker; that is the pre-existing split (list = marker, status = labeled line). This PR preserved it, and no doc claims list prints the count. Adding a labeled count line to list would change its output format beyond the scope of #7805 (the misleading Connected label). Happy to file a follow-up if list/status parity is wanted.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

git show --no-patch --format='%H%n%s' f4e32b5d9 2>/dev/null || true

docs_file=$(fd -t f '^commands\.mdx$' | head -n 1)
inventory_file=$(fd -t f '^index\.ts$' src/lib/inventory | head -n 1)

printf '\n--- docs: relevant headings and SSH-session wording ---\n'
rg -n -C 4 'SSH sessions|### nemoclaw status|### nemoclaw list|session probe' "$docs_file"

printf '\n--- inventory: renderer/status symbols ---\n'
ast-grep outline "$inventory_file" --items all --type function --match 'renderSandboxInventoryText|showStatusCommand' --view expanded

printf '\n--- inventory: relevant implementation excerpts ---\n'
rg -n -A 45 -B 8 'function renderSandboxInventoryText|function showStatusCommand|SSH sessions|activeSessionCount' "$inventory_file"

Length of output: 21596

---

@Dongni-Yang, thanks for the clarification and the verified evidence.

• Finding 1: Confirmed—the updated documentation correctly distinguishes none (a completed probe with zero sessions) from an unavailable probe (line omitted).
• Finding 2: Confirmed—my attribution was incorrect. commands.mdx:3084 documents nemoclaw status, and showStatusCommand renders the labeled count; nemoclaw list intentionally preserves the compact ● session marker. I’m withdrawing that finding.

🐇 ✓

---

✏️ Learnings added

Learnt from: Dongni-Yang
URL: https://github.com/NVIDIA/NemoClaw/pull/7820

Timestamp: 2026-07-29T12:25:06.124Z
Learning: In the NemoClaw CLI, `nemoclaw status` and `nemoclaw list` deliberately use different SSH-session presentations: `showStatusCommand` renders `SSH sessions: <count|none>` when the probe is available, whereas `renderSandboxInventoryText` preserves the compact `●` marker for a positive active session count. Documentation for the labeled count belongs to the `nemoclaw status` section, not `nemoclaw list`.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/actions/sandbox/status-flow.test.ts (1)

151-160: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Cover the complete SSH-session migration contract.

This only exercises detected: true with zero sessions and rejects the exact "Connected: no" string. It would still pass if an unavailable probe incorrectly rendered SSH sessions: none, or if the removed field returned as another Connected: value. Add a detected: false case expecting no SSH sessions: line, and assert no legacy field prefix (for example, /^\s*Connected:/m).

As per path instructions, tests should prove the observable migrated contract rather than only a narrow implementation string.

🤖 Prompt for 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.

In `@src/lib/actions/sandbox/status-flow.test.ts` around lines 151 - 160, Add
coverage to the SSH-session migration tests around showSandboxStatus: add a
detected: false case that verifies the output contains no “SSH sessions:” line,
and strengthen the existing detected: true assertion to reject any legacy
“Connected:” field using a line-anchored prefix check rather than only
“Connected: no”.

Source: Path instructions

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

Nitpick comments:
In `@src/lib/actions/sandbox/status-flow.test.ts`:
- Around line 151-160: Add coverage to the SSH-session migration tests around
showSandboxStatus: add a detected: false case that verifies the output contains
no “SSH sessions:” line, and strengthen the existing detected: true assertion to
reject any legacy “Connected:” field using a line-anchored prefix check rather
than only “Connected: no”.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: cad0b2e4-940c-4a78-84ba-f777548e2a57

📥 Commits

Reviewing files that changed from the base of the PR and between dec587e and 2874b1f.

📒 Files selected for processing (2)

• docs/reference/commands.mdx
• src/lib/actions/sandbox/status-flow.test.ts

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

• docs/reference/commands.mdx

[cjagwani]

Approved exact head 33f09f7 after the .98 maintainer gate. The SSH-session status change and added regression coverage have no remaining security blocker; all commits are validly signed, both advisor lanes report 0 findings, no unresolved current threads remain, the unrelated CI flake passed on retry, and trusted plan 255968d9 passed onboard repair and resume. Documentation review found no user-facing update needed.

[cjagwani]

Exact-head review remains approved at 33f09f710501c58dd7936001637cb04afd8078cc, but the PR is still based on 795de982e26b400009bf1fc0f3826845d79acc4d while current main is 376beb50b6d184675283bdbc4f2eca18d7200a86. Maintainer edits are disabled, so the merge gate needs an author refresh before current-base CI/evidence can be accepted. I will re-gate the next quiet revision. This is a plain handoff comment, not Changes Requested.

[cjagwani]

Correction to my prior handoff: conflict-free base refreshes are explicitly waived. Please do not merge main solely for base currency; preserving exact-head CI/E2E and documentation receipts is preferred unless GitHub reports a real conflict or reviewed behavior requires a change. The existing approval/review evidence remains in force, and I will continue monitoring mergeability. This is a plain coordination comment, not Changes Requested.