fix(onboard): use sudo lsof fallback to identify root-owned port blockers (fixes #726)

[kagura-agent]

Fixes #726

Problem

When a non-root user runs NemoClaw onboarding and port 8080 is occupied by a root-owned process (e.g., docker-proxy, leftover gateway), lsof returns empty output because non-root users cannot see root-owned listeners. The preflight falls through to the net probe which detects EADDRINUSE but cannot identify the blocking process. The user sees:

Could not identify the process using port 8080.
Run: lsof -i :8080 -sTCP:LISTEN

Running that command also returns empty without sudo, leaving the user stuck.

Solution

1. preflight.js: When regular lsof returns empty, automatically retry with sudo lsof to identify root-owned listeners before falling through to the net probe. This gives users actionable process info (name + PID) instead of a generic EADDRINUSE message.

2. onboard.js: Update the user-facing hint to suggest sudo lsof instead of plain lsof.

Testing

All existing preflight tests pass (9/9). The sudo fallback is skipped when lsofOutput is injected (test mode), so no test changes needed.

Summary by CodeRabbit

Release Notes

Bug Fixes

• Enhanced port conflict diagnostics with improved process identification capabilities
• Diagnostic instructions now intelligently suggest elevated privileges when necessary for accessing port information
• Added fallback detection mechanisms for edge cases in port availability checks

[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: 446f698c-8bfc-4cef-a953-39c4881603f4

📥 Commits

Reviewing files that changed from the base of the PR and between e1097a6 and 993f562.

📒 Files selected for processing (2)

• bin/lib/onboard.js
• bin/lib/preflight.js

---

📝 Walkthrough

Walkthrough

The changes add a sudo prefix to the diagnostic command in the onboarding process and implement a retry mechanism in port availability detection. When initial lsof queries return no results, the code now attempts to run the command with sudo before falling back to alternative detection methods.

Changes

Cohort / File(s)	Summary
Diagnostic command suggestion bin/lib/onboard.js	Updates the printed troubleshooting instruction to include sudo prefix in the lsof command when port is unavailable and process cannot be identified.
Port availability detection logic bin/lib/preflight.js	Adds a retry step that attempts sudo lsof when the initial lsof command returns no data rows. If successful, extracts process name and PID; otherwise falls back to existing net probe detection.

Sequence Diagram(s)

sequenceDiagram
    participant Onboard as Onboarding
    participant Preflight as Preflight Check
    participant lsof as lsof (unprivileged)
    participant sudolsof as lsof (with sudo)
    participant netprobe as Net Probe Fallback

    Onboard->>Preflight: Check port availability
    Preflight->>lsof: Run lsof -i :port -sTCP:LISTEN
    lsof-->>Preflight: Empty or header-only response
    Preflight->>sudolsof: Retry with sudo lsof -i :port -sTCP:LISTEN
    alt sudo lsof succeeds with data
        sudolsof-->>Preflight: Process and PID data
        Preflight->>Preflight: Parse first data row
        Preflight-->>Onboard: Return unavailable (process identified)
        Onboard->>Onboard: Display process info in error message
    else sudo lsof fails or returns no data
        sudolsof-->>Preflight: No usable data or error
        Preflight->>netprobe: Fallback to net probe detection
        netprobe-->>Preflight: Detection result
        Preflight-->>Onboard: Return result
    end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A sudo prefix, oh so fine,
Makes lsof see the port line!
When regular commands fail to peek,
We try again—no longer meek.
Now onboarding flows with grace,
As processes reveal their place! ✨

🚥 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 PR title clearly summarizes the main change: using sudo lsof as a fallback to identify root-owned port blockers, directly addressing the linked issue #726.
Linked Issues check	✅ Passed	All code changes directly address the objectives from #726: sudo lsof fallback in preflight.js detects root-owned listeners, and onboard.js updates the user-facing hint to suggest sudo.
Out of Scope Changes check	✅ Passed	All changes are narrowly scoped to fixing the port blocker identification issue for root-owned processes; no unrelated modifications are present.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[wscurran]

Thanks for submitting this PR, it improves the onboarding process by using sudo lsof fallback to identify root-owned port blockers, which could improve the user experience and prevent potential issues for new users.