Document -XX:OnOutOfMemoryError as a way to recover from a crashed agent JVM

[om7057]

Relates to #775

Issue #775 reports that an agent whose JVM runs out of memory on the remote machine stays connected in a broken state and keeps failing every build routed to it, since nothing on the Jenkins side detects that the process is no longer functioning correctly.

I checked whether the two "possible solutions" listed in the issue (monitor exceptions and kill the process, or add a JVM flag to exit on OOM) require a plugin code change, and the second one does not. The jvmOptions field already passes its value straight into the remote java invocation used to launch the agent (SSHLauncher.java, the command built in the launch method), so users can already add -XX:OnOutOfMemoryError="kill -9 %p" or -XX:+ExitOnOutOfMemoryError today. Either makes the JVM terminate immediately on OOM, which lets Jenkins detect the disconnect and retry the launch instead of leaving a dead agent in rotation. The field's help text never mentioned this option, and predates it being documented anywhere in the plugin.

This is a documentation-only change to help-jvmOptions.html, so users encountering #775 get an immediate mitigation without needing to wait on a plugin release. I don't think this fully closes #775, since it doesn't add any proactive detection on Jenkins' side for users who don't set this flag, so I left it as "Relates to" rather than "Fixes". Happy to look at a more proactive code-level fix (the issue's first suggested direction) if maintainers think this documentation mitigation isn't sufficient, but wanted to land the low-risk, immediately actionable part first.

Testing done

Documentation-only change, verified the rendered help text by building the plugin and inspecting the generated SSHConnector/help-jvmOptions.html output. Also confirmed getJvmOptions() is used directly in the launch command construction in SSHLauncher.java before writing this, so the documented flags are actually effective.

Submitter checklist

• Make sure you are opening from a topic/feature/bugfix branch (right side) and not your main branch!
• Ensure that the pull request title represents the desired changelog entry
• Please describe what you did
• Link to relevant issues in GitHub or Jira
• Link to relevant pull requests, esp. upstream and downstream changes
• Ensure you have provided tests that demonstrate the feature works or the issue is fixed (not applicable, documentation-only change)

[Copilot]

Pull request overview

Updates the SSH agent JVM options help text to document JVM flags that force agent termination on OutOfMemoryError, mitigating cases where an OOM’d agent stays “connected” but non-functional (as described in #775).

Changes:

• Expanded help-jvmOptions.html to mention -XX:OnOutOfMemoryError="kill -9 %p" and -XX:+ExitOnOutOfMemoryError as mitigation options for crashed/broken agent JVMs.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.