Skip to content

feat(cli): report paired host platforms with bounded, read-only probes - #18946

Open
nwparker wants to merge 11 commits into
stablyai:mainfrom
nwparker:orca-host-list-paired-metadata
Open

nwparker wants to merge 11 commits into
stablyai:mainfrom
nwparker:orca-host-list-paired-metadata

Conversation

@nwparker

@nwparker nwparker commented Sep 5, 2026 •

Copy link
Copy Markdown
Contributor

What this does

orca host list is the "what can I target, and what do I type" command. Before this PR it answered that well for SSH targets but barely at all for paired Orca servers — they showed up as a bare name with no platform and no connectivity:

local        this machine  darwin                     ->  --host local
ssh target   openclaw      linux             connected  ->  --host ssh:tgt_9f2c
orca server  awin          platform unknown             ->  --environment awin
orca server  m4air         platform unknown             ->  --environment m4air

Now paired servers report the same two facts SSH targets do — what OS they run and whether they answer right now:

local        this machine  darwin                                        ->  --host local
ssh target   openclaw      linux             connected                   ->  --host ssh:tgt_9f2c
orca server  awin          win32             connected [probe]           ->  --environment env_7ab1
orca server  m4air         darwin            connected [probe]           ->  --environment env_04de
orca server  oldbox        platform unknown  connection unknown [probe] (runtime_timeout)  ->  --environment env_bb30

Follow-up to merged #18896, which added the SSH half of this. That PR is also corrected here (see Fixes to #18896 below).

How paired servers are queried

  • Platform comes from the host itself via the existing status.get → hostPlatform field, falling back to the older host.platform RPC. No new wire fields, so no server update is needed and mixed-version pairs keep working. If neither answers, the row says platform unknown — it is never guessed from the name.
  • Connectivity is a fresh CLI probe, not a read of the desktop app's persistent connection. That distinction is surfaced deliberately: [probe] in text, connectionSource: "probe" in JSON. A successful status.get means connected: true.
  • A failed probe keeps the row and reports connectionStatus: "unknown" with a sanitized probeError (runtime_timeout / status_unavailable / probe_failed). It never reports not connected, and it never emits remote error text, addresses, or credentials. Per the SSH execution boundary, silence from a host is not evidence that the host or its processes are gone.
  • A rejection is not silence. If the server answers and refuses the call — revoked pairing, say — the reply itself proves contact, so the row reports connected: true with probeError: "status_rejected". That tells you to re-pair rather than go debug the network.
  • Selectors use the stable environment ID, so two servers with the same name are still individually addressable. Unique names still resolve as before.

Cost and side effects

Listing is read-only and bounded. At most 4 concurrent probes and a 5s total budget for the whole paired-server scan (legacy platform fallbacks included). The deadline aborts in-flight requests and skips queued ones. Saved pairing metadata and last-used ordering are untouched.

If you want a listing with no network traffic at all, orca environment list still does that.

Fixes to #18896

  • listSshTargets fanned out one ssh.getState per target on every call with an unbounded Promise.all — including selector-resolution calls that only need names to build an error message. The fan-out is now inventory-only, capped at 4, and budget-bounded.
  • An unreadable SSH inventory used to return [], which is indistinguishable from "this machine has no SSH targets". It now prints an explicit incomplete-list warning.
  • Dropped the redundant connected (connected) text; the lifecycle detail only prints when it adds information.
  • One-shot probe sockets that fail or are aborted now terminate() instead of close(), so a half-open peer can't hold the socket open through a close handshake.

Review round: three things this PR got wrong

Caught in review of an earlier head and fixed in a3493c61aa3.

SSH connected must stay authoritative. An earlier revision made ssh.listTargetSummaries omit connected when a target had no live connection object, on the theory that absence of state means "we don't know". It doesn't. Whether this app holds an SSH connection is a local fact the app knows for certain — the live/unverifiable/exited vocabulary governs remote process state, not our own socket table. Since getPublicSshState returns undefined for every target that hasn't connected in this session, the effect was that a fresh app launch or an ~/.ssh/config import made every SSH target print connection unknown. Reverted to connected: state?.status === 'connected'.

That also caused a silent fan-out. The target.connected !== undefined short-circuit in listSshTargets was keyed on that field always being present. With it omitted, every idle target got an ssh.getState round-trip that returns {state: null} and merges nothing — 40 imported ssh-config hosts meant 40 guaranteed-useless RPCs against the shared budget. Fixed by the revert above; pinned by a test.

The enumeration call shouldn't share the fan-out budget. It was capped at 5s, down from the 60s client default, and on failure the inventory path rethrows into an "SSH inventory unavailable" warning. So one briefly busy main process — cold start, large git operation — replaced the entire SSH inventory with a warning, all-or-nothing, where before it simply waited. The enumeration call now keeps the default timeout; only the per-target fan-out, which is the actually-unbounded part, is charged against the 5s budget.

Also: host list help said --environment <name> while host list output printed --environment <id>. Help now matches. (omitted-host-scope-selectors.ts still emits the name form for a different command's scope line — pre-existing, both forms resolve, left alone.)

Files

New src/cli/handlers/paired-host-inventory.ts holds the probe logic, with colocated unit and encrypted-wire tests. Everything else reuses existing pieces: the shared SSH contract types, mapWithConcurrency, and the existing remote-runtime transport. CLI help, docs/site/.../cli/reference.mdx, the bundled agent guide and its generated artifact are updated.

Verification

Rebuilt CLI run against real saved hosts, no server state modified:

Host Platform Evidence
openclaw linux app-owned SSH connection
awin win32 successful paired probe
m4air darwin successful paired probe
win-lowspec win32 successful paired probe

Full src/cli suite plus the transport and SSH-RPC tests: 1259 tests, 128 files, all passing. Deterministic 100-host tests pin the concurrency cap and deadline behavior; authenticated WebSocket tests cover old-server fallback, mid-flight drop, keepalive-cannot-extend-the-deadline, and socket release. New regression tests cover the three review fixes: no-live-state reports connected: false, idle targets are not re-queried, the enumeration call is not passed a shrunken timeout, and a refusal reports proven contact. CLI + node typechecks, changed-code quality, and guide/manifest verification pass.

Not verified: no physical Wi-Fi/sleep/SSH-disconnect chaos testing and no mobile-device run — network failure coverage is controlled WebSocket fixtures, not a real outage. No Electron UI changed.

Note on semantics: paired connected: true means this CLI reached the server. It does not mean the desktop app holds a persistent link, nor that everything on that host is healthy. SSH connected is a different and stronger claim: the app knows whether it holds that connection.

@coderabbitai

coderabbitai Bot commented Sep 5, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

The CLI host listing now includes local, registered SSH, and paired hosts. SSH rows can include connection state and remote platform data. Paired rows use bounded runtime probes with legacy platform fallback, sanitized errors, and stable selectors. The listing preserves rows when probes or SSH inventory fail and reports warnings for incomplete SSH inventory. Formatting displays probe metadata and warnings. RPC socket termination and test-server controls were updated to validate timeout cleanup. CLI documentation and command notes describe the new behavior.

Merge Risk: 🔵 Low · up to 6f7dc

The test server cannot currently emit explicitly configured null or missing result payloads, limiting coverage of malformed runtime responses. This is bounded to test infrastructure but should be corrected.

🚥 Pre-merge checks | ✅ 1 | ❌ 4

❌ Failed checks (4 warnings)

Check name Status Explanation Resolution
Linked Issues check ⚠️ Warning The linked issue [#18955] requires changes to three artifact-service test files so ordinary fixtures expire 30 days after creation. The provided changeset contains paired-host, SSH inventory, CLI form… Add the required changes to the three artifact-service test files, or remove [#18955] and link the issue that covers the paired-host and SSH host-list objectives.
Out of Scope Changes check ⚠️ Warning Relative to linked issue [#18955], the paired-host probing, SSH inventory, CLI formatting, documentation, and remote-runtime transport changes are unrelated out-of-scope changes. Split the host-list implementation into a PR linked to its relevant issue, and keep this PR limited to the artifact-service fixture expiry changes required by [#18955].
Docstring Coverage ⚠️ Warning Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 16 files. (2 skipped:… Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check ⚠️ Warning The description gives a detailed explanation of the implementation, behavior, limitations, and verification. However, it does not follow the repository template: the required ELI5, Why, Linked Issue w… Add the missing template sections and include the required linked issue in the form Fixes #<number>. Add N/A with a reason under Visual Proof if no UI or interaction changed. Preserve the existing technical details under the matching te…
✅ Passed checks (1 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the primary change: reporting paired host platforms through bounded, read-only CLI probes.
Full details: Linked Issues check

Explanation

The linked issue [#18955] requires changes to three artifact-service test files so ordinary fixtures expire 30 days after creation. The provided changeset contains paired-host, SSH inventory, CLI formatting, documentation, and transport changes, with no artifact-service fixture changes shown. The description says the issue was fixed upstream, but this does not demonstrate that this PR implements the linked issue.

Full details: Docstring Coverage

Explanation

Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 16 files. (2 skipped: 2 unsupported.)

Full details: Description check

Explanation

The description gives a detailed explanation of the implementation, behavior, limitations, and verification. However, it does not follow the repository template: the required ELI5, Why, Linked Issue with a Fixes reference, Visual Proof or exact N/A statement, Testing, Review, Agent skill upstream boundary, Notes, and Checklist sections are missing or renamed.

Resolution

Add the missing template sections and include the required linked issue in the form Fixes #&lt;number&gt;. Add N/A with a reason under Visual Proof if no UI or interaction changed. Preserve the existing technical details under the matching template headings.

  • Fix all pre-merge checks with AI

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Team

Run ID: 69c14980-eb21-4df0-ba6d-b1da0939210f

📥 Commits

Reviewing files that changed from the base of the PR and between 59756b8 and e8505cd.

📒 Files selected for processing (10)
  • docs/site/content/docs/cli/reference.mdx
  • src/cli/format.ts
  • src/cli/handlers/environment.ts
  • src/cli/host-selector-alternatives.test.ts
  • src/cli/host-selector-alternatives.ts
  • src/cli/index-local-command-routing-flags.test.ts
  • src/cli/specs/environment.ts
  • src/main/runtime/rpc/methods/ssh.test.ts
  • src/main/runtime/rpc/methods/ssh.ts
  • src/shared/ssh-types.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 0 remain after this review.

Comment thread src/main/runtime/rpc/methods/ssh.ts Resolved

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ No blocking issues — one consistency nit inline and a few rough edges below.

Reviewed changes

  • Paired-server metadata — each paired environment is probed live via status.get and reported with platform, connected, and connectionStatus; any probe failure renders the row disconnected without exposing pairing credentials or endpoints.
  • SSH target metadata — ssh.listTargetSummaries and the legacy ssh.listTargets now carry connected, connectionStatus, and remotePlatform, with a CLI-side ssh.getState enrichment fallback for hosts that only serve ssh.listTargets.
  • Formatting, types, docs — HostListEntry/formatHostConnection gain the new columns, the shared SshTargetSummary type is extended, and the CLI reference and command specs are updated.

ℹ️ Nitpicks

  • src/cli/host-selector-alternatives.ts:8 redefines SshTargetSummary with connectionStatus?: string while src/shared/ssh-types.ts types the field as SshConnectionStatus; the CLI copy is a looser duplicate that can drift from the shared contract.
  • connectionStatus in host list --json mixes two vocabularies — SshConnectionStatus (auth-failed, deploying-relay, …) for SSH rows vs RuntimeHostConnectionState (runtime-unavailable, workspace-window-closed, …) for paired-server rows. Scripts reading that field must handle both.
  • host list used to be a purely local read; it now makes one status.get round-trip per paired server (5 s timeout, Promise.all-bounded). Offline servers add up to ~5 s latency to a previously instant command — a user-visible behavior change worth a release note.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using DeepSeek Pro (free via Pullfrog for OSS) | 𝕏

Comment thread src/main/runtime/rpc/methods/ssh.ts Resolved
@nwparker nwparker changed the title feat(cli): report paired server host metadata feat(cli): report paired host platforms with bounded, read-only probes Sep 6, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes (delta since the prior review at e8505cd)

  • Paired-server probing — extracted into paired-host-inventory.ts with a four-connection concurrency cap and a five-second total scan budget via AbortController, removing the unbounded Promise.all latency the prior review flagged.
  • SSH inventory fanout — legacy ssh.getState enrichment is now mapWithConcurrency-bounded with a shared deadline; host list surfaces an incomplete-inventory warning instead of silently dropping SSH targets when the runtime is unavailable.
  • Probe socket teardown — failed or aborted one-shot sockets terminate() rather than close(), so a half-open peer cannot keep a socket lingering past the deadline.
  • Conditional connected — ssh.ts now omits connected when no registered state exists, addressing the prior inline comment.
  • Type + docs — re-exported the shared SshTargetSummary instead of a looser local duplicate, and documented the probe semantics ([probe] / connectionSource / probeError) in the CLI reference and skill guide.

Pullfrog  | View workflow run | Using DeepSeek Pro (free via Pullfrog for OSS) | 𝕏

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes (delta since the prior review at 3af78e2)

  • Host connectivity text coverage — added host-list-format.test.ts, which pins the formatHostList connection labels (connected / not connected (…) / connection unknown) and asserts the redundant connected (connected) text stays gone.
  • Shared SSH contract reuse — dropped the local SshTargetSummary duplicate in host-selector-alternatives.ts and re-exported the shared type, narrowing ssh.getState's enrichment status / remotePlatform to SshTargetSummary['connectionStatus'] / ['remotePlatform']. This fully resolves the prior connectionStatus?: string drift nitpick.

Pullfrog  | View workflow run | Using DeepSeek Pro (free via Pullfrog for OSS) | 𝕏

@coderabbitai

coderabbitai Bot commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes (delta since the prior pullfrog review at 52f154b)

  • Malformed-status guard — paired-host-inventory.ts now rejects status.get results that are falsy, non-object, or arrays (status_unavailable instead of a false connected: true), so a malformed payload can no longer masquerade as a verified probe.
  • Regression coverage — added an it.each([null, undefined, 42, 'not a status', []]) case pinning the guard, plus a keepalive-only wire test proving the 5 s whole-scan deadline still holds while a peer sends keepalives.
  • Test-server support — remote-runtime-shared-control-test-server.ts gained results and activeConnectionCount to back the new wire cases.
  • Guide regeneration — combined CLI guides were regenerated from the main merge; no PR-specific content change.

Pullfrog  | View workflow run | Using DeepSeek Pro (free via Pullfrog for OSS) | 𝕏

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Team

Run ID: 4fa5bd9f-ae43-4321-b088-ac38f8c65959

📥 Commits

Reviewing files that changed from the base of the PR and between 98b0c32 and 6f7dc81.

📒 Files selected for processing (18)
  • docs/site/content/docs/cli/reference.mdx
  • skill-guides/orca-cli.md
  • src/cli/bundled-skill-guides.ts
  • src/cli/format.ts
  • src/cli/handlers/environment.ts
  • src/cli/handlers/paired-host-inventory-wire.test.ts
  • src/cli/handlers/paired-host-inventory.test.ts
  • src/cli/handlers/paired-host-inventory.ts
  • src/cli/host-list-format.test.ts
  • src/cli/host-selector-alternatives.test.ts
  • src/cli/host-selector-alternatives.ts
  • src/cli/index-local-command-routing-flags.test.ts
  • src/cli/specs/environment.ts
  • src/main/runtime/rpc/methods/ssh.test.ts
  • src/main/runtime/rpc/methods/ssh.ts
  • src/shared/remote-runtime-client.test.ts
  • src/shared/remote-runtime-request-socket.ts
  • src/shared/remote-runtime-shared-control-test-server.ts
🚧 Files skipped from review as they are similar to previous changes (2)
  • src/main/runtime/rpc/methods/ssh.test.ts
  • src/main/runtime/rpc/methods/ssh.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 5 remain after this review.

const result = streaming
? { type: 'ready', subscriptionId: `${request.method}:subscription` }
: { method: request.method }
: (options.results?.[request.method] ?? { method: request.method })

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Preserve explicit null and undefined fixture results.

Line 180 treats a configured null or undefined result as an absent entry. The server then returns the default result. This prevents wire tests from producing malformed missing or null result payloads through results.

Proposed fix
-    : (options.results?.[request.method] ?? { method: request.method })
+    : (Object.hasOwn(options.results ?? {}, request.method)
+        ? options.results![request.method]
+        : { method: request.method })
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
: (options.results?.[request.method] ?? { method: request.method })
: (Object.hasOwn(options.results ?? {}, request.method)
? options.results![request.method]
: { method: request.method })

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant