fix(ssh): actionable error when an SSH agent targets a Windows remote (#995)

[jSydorowicz21]

Summary

Addresses #995. Root cause (high confidence): Maestro's SSH command builders are POSIX-only (they hardcode /bin/bash --norc --noprofile and POSIX quoting), so any agent (including Copilot CLI) crashes with a cryptic exit 1 when the SSH remote host is Windows.

This PR converts that cryptic crash into a clear, actionable failure.

Changes

• Detect Windows-shell failure signatures (cmd.exe / PowerShell "is not recognized...", "the system cannot find the path specified") in the SSH error-pattern layer and surface: "SSH execution to Windows remote hosts is not yet supported ... See issue Copilot CLI Agent crashes via Windows SSH session #995."
• POSIX (Linux/macOS) remotes are unaffected; the signatures are Windows-exclusive (a POSIX command not found still maps to its own message).
• 5 new unit tests.

Scope / deferred

Full Windows-remote command generation (cmd.exe vs PowerShell selection, quoting of args/cwd/env, remote PATH and copilot.exe resolution) is intentionally deferred: it cannot be verified without a live Windows SSH host, and shipping a speculative command into a security-sensitive execution path would be a guess. This PR is the verifiable guardrail; the full fix can follow once a Windows SSH test target is available.

Verification

• npm run lint (tsc x3): clean
• vitest run error-patterns: 130 tests pass (incl. 5 new)
• eslint + prettier: clean

Summary by CodeRabbit

• Bug Fixes
  • Improved SSH error handling to give a clearer message when connecting to a Windows remote host that doesn’t support the expected shell environment.
  • These failures are now marked as non-recoverable and explain that the remote setup is not yet supported.
• Tests
  • Added regression coverage for Windows-specific SSH failures and checks to avoid false positives on normal POSIX remote errors.

[greptile-apps]

Greptile Summary

This PR makes Windows SSH remote failures easier to understand. The main changes are:

• Adds an unsupported-Windows-remote message for SSH execution.
• Maps cmd.exe and PowerShell shell-failure signatures to that message.
• Adds tests for Windows signatures and POSIX non-matches.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
src/main/parsers/error-patterns.ts	Adds SSH error patterns that convert Windows remote shell failures into a clear unsupported-remote message.
src/tests/main/parsers/error-patterns.test.ts	Adds tests for the new Windows SSH error signatures and POSIX cases that should not use the Windows message.

_{Reviews (2): Last reviewed commit: "fix(ssh): surface actionable error for W..." | Re-trigger Greptile}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2b5f8118-d0d8-4d13-ae90-bc0d00108610

📥 Commits

Reviewing files that changed from the base of the PR and between 9972eee and a1bec0c.

📒 Files selected for processing (2)

• src/__tests__/main/parsers/error-patterns.test.ts
• src/main/parsers/error-patterns.ts

---

📝 Walkthrough

Walkthrough

SSH error-pattern matching now recognizes Windows remote host failures that cannot run the POSIX shell command it builds, returns a non-recoverable agent_crashed result with a Windows-specific message, and adds regression coverage for matching and false-positive cases.

Changes

Windows remote SSH handling

Layer / File(s)	Summary
Unsupported Windows remote message src/main/parsers/error-patterns.ts	Adds WINDOWS_REMOTE_UNSUPPORTED_MESSAGE, documents POSIX-only SSH remotes, and maps Windows cmd.exe, PowerShell, and path-not-found stderr to a non-recoverable agent_crashed result.
Windows remote regression tests src/__tests__/main/parsers/error-patterns.test.ts	Adds agent_crashed coverage for Windows remote host failures and negative cases for POSIX command-not-found output and unrelated /bin/bash text.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

approved, ready to merge

Poem

A bunny hopped through the SSH night,
And found Windows shells lacking bash in sight.
A carrot of clarity twitched in the air,
agent_crashed replied with rabbit care.
Hop-hop — the false paths were left behind.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding an actionable SSH error for Windows remote hosts.
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.

✨ 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 triage/issue-995-windows-ssh-guard

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed due to a network error.

---

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

[jSydorowicz21]

@greptile re-review please