fix(ssh): fix reconnect issues and node binary path resolution

[juliusmarminge]

Summary

Fixes SSH launcher failure modes reported from remote Linux hosts:

• bootstrap now recovers Node in non-interactive sh -s SSH sessions before running remote Node helper scripts or the T3 runner
• Node discovery handles common install locations and version managers, including Volta, asdf, mise, fnm, nodenv, and nvm
• the standalone SSH launcher accepts the required Node engine range as an option; the desktop app passes apps/server/package.json's engines.node range and the selected remote Node is validated before launch
• reconnect after desktop app updates no longer reuses a launcher-managed remote server as if it were external; it stops stale managed processes and clears SSH state before relaunching
• launch and pairing output parsing now tolerates shell startup noise before the final JSON payload
• REMOTE.md now documents SSH launch troubleshooting, Node requirements, version-manager resolution, and reconnect cleanup behavior

Closes #2534

Root Cause

The remote bootstrap ran under non-interactive sh, so hosts with Node exposed only through shell setup from a version manager could fail with node: command not found during port picking/readiness. Even when a Node binary was found, the launcher did not check that it satisfied the server package's runtime engine range before starting helper scripts and the server. Separately, the shared remote runtime file could make a launcher-managed process look like an external server before runner-change restart logic ran, leaving users stuck after updates unless they manually killed remote t3code state.

Validation

• bun fmt
• bun lint (passes with existing warnings)
• bun typecheck
• bun run --filter @t3tools/ssh test

---

Note

Medium Risk
Medium risk: changes the SSH bootstrap/launch scripts and remote server reuse logic, which can affect connectivity and remote process lifecycle across diverse host environments. Also replaces version-comparison utilities used for provider/CLI gating, which could alter upgrade/advisory behavior if edge cases differ.

Overview
Hardens desktop-managed SSH launch/reconnect on remote hosts. The SSH bootstrap now tries to locate/activate a compatible remote node in non-interactive sh sessions (common paths + Volta/asdf/mise/fnm/nodenv/nvm), and can enforce a required Node engine range before running helper scripts or starting t3.

Launch/pairing output decoding is made resilient to shell startup noise by extracting the JSON object from stdout before decoding. Reconnect behavior is adjusted to avoid treating stale launcher-managed servers as “external” by stopping them and clearing/refreshing saved PID/port state.

Separately, a shared @t3tools/shared/semver module is introduced (with tests) and replaces the server’s custom cliVersion comparator; extractJsonObject is moved into @t3tools/shared/schemaJson and reused by text-generation and SSH parsing. REMOTE.md gains detailed SSH launch troubleshooting and Node requirements.

^{Reviewed by Cursor Bugbot for commit c4be90c. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Fix SSH reconnect issues and Node binary path resolution for remote launch

• Remote launch and runner scripts now bootstrap Node onto PATH for non-interactive shells by probing common install locations and initializing version managers (volta, asdf, mise, fnm, nodenv, nvm) via REMOTE_NODE_ENV_SCRIPT in tunnel.ts
• Adds optional Node engine range enforcement: a self-contained satisfiesSemverRange implementation (valid plain JS for remote execution) is stringified and sent to the remote host to validate the Node version before proceeding
• SSH launch and pairing token output parsing now tolerates shell startup noise by extracting JSON from mixed stdout via a new decodeRemoteJsonOutput helper
• Consolidates semver utilities into a new @t3tools/shared/semver package, replacing local compareCliVersions in ClaudeProvider, OpenCodeProvider, and providerMaintenance
• Moves extractJsonObject to @t3tools/shared/schemaJson, removing duplication from TextGenerationUtils

^{Macroscope summarized c4be90c.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: d1656d40-cd49-4d1b-9d28-920181e5a609

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/11970999

---

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

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces substantial SSH launch behavior changes including node version manager detection and reconnect handling. Three unresolved review comments identify potential bugs: JSON extraction may fail with certain shell output, misleading error messages, and risk of killing external servers. These substantive issues warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

JSON extraction finds first brace, not last payload

Medium Severity

decodeRemoteJsonOutput falls back to extractJsonObject which finds the first { in stdout, not the last JSON payload. If shell startup noise from version managers contains any { character (e.g., nvm: {default} or asdf: update {notice}), the extraction grabs the wrong substring, decoding fails, and the valid JSON payload later in the output is never attempted — causing a spurious SSH launch or pairing failure.

Additional Locations (1)

• packages/shared/src/schemaJson.ts#L99-L146

 

^{Reviewed by Cursor Bugbot for commit 394dc29. Configure here.}

[cursor]

Misleading error when node version fails range check

Low Severity

When ensure_remote_node_path fails because the discovered node doesn't satisfy the engine range (not because node is missing), the launch script prints "Remote host is missing node on PATH" which contradicts the earlier stderr message from remote_node_satisfies_engine saying the node version doesn't satisfy the required range. Users troubleshooting SSH launch failures would see conflicting guidance.

 

^{Reviewed by Cursor Bugbot for commit 394dc29. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Caret operator incorrect for semver major version zero
  • Added special-case handling for the caret operator when major is zero: pins minor when major=0 and minor!=0, and pins patch when both major=0 and minor=0, matching the semver specification.

Or push these changes by commenting:

@cursor push 6d301562d5

Preview (6d301562d5)

diff --git a/packages/shared/src/semver.ts b/packages/shared/src/semver.ts
--- a/packages/shared/src/semver.ts
+++ b/packages/shared/src/semver.ts
@@ -188,7 +188,20 @@
         const operator = match[1] || "=";
         switch (operator) {
           case "^":
-            return version.major === target.major && compared >= 0;
+            if (target.major !== 0) {
+              return version.major === target.major && compared >= 0;
+            }
+            if (target.minor !== 0) {
+              return (
+                version.major === target.major && version.minor === target.minor && compared >= 0
+              );
+            }
+            return (
+              version.major === target.major &&
+              version.minor === target.minor &&
+              version.patch === target.patch &&
+              compared >= 0
+            );
           case ">=":
             return compared >= 0;
           case ">":

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Fallback PID may kill external server unintentionally
  • Removed the ${REMOTE_PID:-$DEFAULT_RUNTIME_PID} fallback so PID_TO_STOP is set to $REMOTE_PID directly, preventing an empty REMOTE_PID from resolving to the external server's PID.

Or push these changes by commenting:

@cursor push a2607dec13

Preview (a2607dec13)

diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -546,7 +546,7 @@
   REMOTE_PORT="$DEFAULT_REMOTE_PORT"
   if wait_ready "@@T3_REUSE_READY_TIMEOUT_MS@@"; then
     if [ "$REMOTE_MANAGED" = "managed" ]; then
-      PID_TO_STOP="\${REMOTE_PID:-$DEFAULT_RUNTIME_PID}"
+      PID_TO_STOP="$REMOTE_PID"
       if [ -n "$PID_TO_STOP" ] && kill -0 "$PID_TO_STOP" 2>/dev/null; then
         kill "$PID_TO_STOP" 2>/dev/null || true
         wait_for_pid_exit "$PID_TO_STOP"

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit c4be90c. Configure here.}

[cursor]

Fallback PID may kill external server unintentionally

Medium Severity

When REMOTE_MANAGED is "managed" but REMOTE_PID is empty (e.g., PID file was deleted or corrupted), PID_TO_STOP falls back to DEFAULT_RUNTIME_PID via "${REMOTE_PID:-$DEFAULT_RUNTIME_PID}". DEFAULT_RUNTIME_PID comes from server-runtime.json and may represent an externally started server. Killing it defeats the purpose of adopting an external server, as the subsequent wait_ready on that port will fail, forcing an unnecessary full relaunch. The fallback should only kill the process we actually launched (i.e., only when REMOTE_PID is non-empty).

 

^{Reviewed by Cursor Bugbot for commit c4be90c. Configure here.}