fix(ssh): keep orchestration check help side-effect free

[innocarpe]

Description

Prevent the SSH legacy fallback from executing orchestration check when a user only asks for help.

Focused fix

• In scope: return the existing command usage before legacy RPC dispatch for orca orchestration check --help.
• Out of scope: normal local CLI help, passthrough-capable hosts, and non-help orchestration commands.

Preserves

• Mailbox reads, acknowledgements, and other orchestration side effects remain unchanged for commands that actually execute.

Evidence

• Test: pnpm exec vitest run --config config/vitest.config.ts src/main/ssh/ssh-remote-orca-cli.test.ts
• Test: pnpm exec vitest run --config config/vitest.config.ts src/main/ssh/ssh-remote-orca-cli.test.ts src/main/ssh/ssh-remote-cli-host-passthrough.test.ts
• Typecheck: pnpm run typecheck:node
• Changed-code quality: pnpm run check:code-quality:changed -- upstream/main
• Regression coverage asserts help succeeds without calling the orchestration database paths.

User-regression-tradeoffs

• Legacy SSH hosts now match the local CLI's side-effect-free help contract; the fallback owns only the existing check help text and does not change command execution.

Fixes #12985

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a11cf0b8-4c8a-4143-a47f-f6e9993e169b

📥 Commits

Reviewing files that changed from the base of the PR and between 595097b and e70862b.

📒 Files selected for processing (3)

• src/main/ssh/ssh-remote-orca-cli.test.ts
• src/main/ssh/ssh-remote-orca-cli.ts
• src/main/ssh/ssh-remote-orchestration-help.ts

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

• src/main/ssh/ssh-remote-orca-cli.ts
• src/main/ssh/ssh-remote-orca-cli.test.ts
• src/main/ssh/ssh-remote-orchestration-help.ts

---

📝 Walkthrough

Walkthrough

The SSH legacy remote CLI now resolves orchestration check --help before linear help handling or command dispatch. The new resolver provides command-specific help text for message retrieval, acknowledgement, waiting, keepalive output, filtering, and formatting options. Regression coverage verifies the exact output, successful exit, empty stderr, and absence of orchestration database access.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the fix and testing but omits the required AI review, security audit, screenshots, and notes sections.	Add the missing template sections, state "No visual change" where applicable, and document AI review, cross-platform checks, security risks, and follow-up notes.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the SSH orchestration help fix and its side-effect-free behavior.
Linked Issues check	✅ Passed	The changes make legacy SSH help side-effect free and add regression coverage for issue #12985.
Out of Scope Changes check	✅ Passed	The changed files and tests are limited to legacy SSH orchestration help handling and directly support issue #12985.

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 83ca91ad-77c9-4d65-b5f9-25c1cb862b79

📥 Commits

Reviewing files that changed from the base of the PR and between 7e60b33 and 3ef55de.

📒 Files selected for processing (3)

• src/main/ssh/ssh-remote-orca-cli.test.ts
• src/main/ssh/ssh-remote-orca-cli.ts
• src/main/ssh/ssh-remote-orchestration-help.ts

[innocarpe]

Sync update (e70862b7cb)

Addressed review: the legacy help test now proves that getOrchestrationDb is never accessed, and the SSH orchestration help options now match the command contract. Validation: 23 SSH tests, full typecheck, and changed-code quality passed.

• Commit: e70862b7cb903dc207c1cba82e17be984083beec
• Upstream: fix(ssh): keep orchestration check help side-effect free #12996
• Fork portfolio: [upstream #12996] fix(ssh): keep orchestration check help side-effect free innocarpe/orca#154

[coderabbitai]

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.