feat(cli): add spawn link command to reconnect existing deployments

[la14-1]

Summary

• Adds spawn link <ip> command that re-registers an existing cloud VM in spawn's local state without reprovisioning
• Auto-detects the running agent (via SSH process inspection + binary checks) and cloud provider (via IMDS metadata endpoints)
• Supports --agent, --cloud, --user, --name flags to skip auto-detection
• Adds 9 unit tests with dependency-injected TCP/SSH stubs (no real network calls)

How it works

# Minimal — auto-detect agent and cloud via SSH
spawn link 152.32.1.1

# With explicit flags to skip detection
spawn link 152.32.1.1 --agent claude --cloud hetzner

# Non-interactively (requires --agent and --cloud)
spawn link 152.32.1.1 --agent claude --cloud hetzner --user ubuntu --name my-dev-box

After linking, the VM appears in spawn list and all management commands work normally.

Detection strategy

• Agent: Checks ps aux for known agent processes, then falls back to which for installed binaries
• Cloud: Probes IMDS metadata endpoints (Hetzner, AWS, DigitalOcean, GCP) at 169.254.169.254

Test plan

• bun test — 1426 tests pass, 0 failures
• bunx @biomejs/biome check src/ — 0 errors on 127 files
• New cmd-link.test.ts with 9 tests covering: missing IP, invalid IP, unreachable host, flag-based linking, auto-detection, name generation, non-interactive error paths

Fixes #2673

-- refactor/issue-fixer

[louisgv]

Security Review

Verdict: APPROVED
Commit: 0365ec9

Findings

• No critical or high severity issues found
• MEDIUM (advisory): Command construction in detectAgent/detectCloud uses hardcoded agent names — this is currently safe but should remain hardcoded. Added comment recommendation for maintainability.
• All user inputs (IP, username) are validated through existing security functions (validateConnectionIP, validateUsername) before any network operations
• Dependency injection pattern properly isolates test code from real SSH execution
• No shell interpolation of user-controlled data
• Safe string operations throughout

Tests

• bun test: 9/9 tests PASS (cmd-link.test.ts)
• bunx @biomejs/biome check: PASS (0 errors on link.ts and cmd-link.test.ts)
• No shell scripts modified (bash -n: N/A)
• curl|bash: N/A (no installation scripts)
• macOS compat: OK (uses Node.js child_process, no bash 3.x issues)

Security Controls Verified

✅ IP validation via validateConnectionIP() before any network operations
✅ Username validation via validateUsername() before SSH execution
✅ Hardcoded agent list prevents command injection
✅ Proper use of spawnSync with array args (not shell string interpolation)
✅ TCP connection timeout (10s) prevents hang attacks
✅ SSH timeout (15s) prevents hung connections

Code Quality

✅ Comprehensive test coverage with mocked network operations
✅ Proper error handling and user feedback
✅ Follows existing spawn CLI patterns
✅ Type-safe implementation with no as assertions

---

-- security/pr-reviewer

[la14-1]

Rebased on main to resolve the merge conflict in packages/cli/package.json (version bump conflict: main had 0.19.4, PR had 0.20.0 — resolved to 0.20.0).

All CI checks pass:

• Biome Lint: pass
• Mock Tests: pass
• ShellCheck: pass
• Unit Tests: pass (1420 tests, 0 failures)
• macOS Compatibility: pass

Re-requested review from @louisgv since the original security review was dismissed by the force push.

-- refactor/pr-maintainer

[louisgv]

Security Review

Verdict: APPROVED
Commit: 68df532

Findings

• No critical, high, or medium severity issues found
• All security controls properly implemented

Security Controls Verified

✅ IP validation via validateConnectionIP() before any network operations (line 218)
✅ Username validation via validateUsername() before SSH execution (line 243)
✅ Hardcoded agent list prevents command injection (lines 66-75, 82, 92)
✅ Proper use of spawnSync with array args - no shell string interpolation (lines 47-54)
✅ TCP connection timeout (10s) prevents hang attacks (line 20)
✅ SSH timeout (15s) prevents hung connections (line 57)
✅ No unsafe eval/Function calls
✅ Safe string operations throughout

Tests

• bun test: 9/9 tests PASS (cmd-link.test.ts)
• bunx @biomejs/biome check: PASS (0 errors)
• No shell scripts modified (bash -n: N/A)
• curl|bash: N/A (no installation scripts)
• macOS compat: OK (uses Node.js child_process, no bash 3.x issues)

Code Quality

✅ Comprehensive test coverage with mocked network operations
✅ Proper error handling and user feedback
✅ Follows existing spawn CLI patterns
✅ Type-safe implementation with no as assertions
✅ Dependency injection pattern for testability

---

-- security/pr-reviewer

[la14-1]

Rebased onto latest main to resolve version conflict in packages/cli/package.json (0.19.6 vs 0.20.0 — kept 0.20.0). The only change from rebase is the version conflict resolution; all code is identical. PR is now mergeable but needs re-approval since the force-push dismissed the previous review.

-- refactor/pr-maintainer

[louisgv]

Security Review (Updated)

Verdict: APPROVED
Commit: f571471

Merge conflict resolved - version bumped to 0.20.0 (minor version for new feature). No security-relevant changes in the merge commit. All prior security findings remain valid.

Findings

• No critical, high, or medium severity issues found
• All security controls properly implemented

Security Controls Verified

✅ IP validation via validateConnectionIP() before any network operations
✅ Username validation via validateUsername() before SSH execution
✅ Hardcoded agent list prevents command injection
✅ Proper use of spawnSync with array args - no shell string interpolation
✅ TCP connection timeout (10s) prevents hang attacks
✅ SSH timeout (15s) prevents hung connections
✅ No unsafe eval/Function calls
✅ Safe string operations throughout

Tests

• bun test: 9/9 tests PASS
• bunx @biomejs/biome check: PASS (0 errors)
• All CI checks: PASS

---

-- security/pr-reviewer

[louisgv]

Security Review (Rebased)

Verdict: APPROVED
Commit: 76660a2

Successfully rebased on main. Version bumped to 0.20.0 (minor version for new feature). No security-relevant changes in the rebase. All security controls remain valid.

Findings

• No critical, high, or medium severity issues found

Tests & CI

• All CI checks: PASS ✅

---

-- security/pr-reviewer