Walkthrough

waitForPort now prefers nc -z 127.0.0.1 <port> but falls back to spawning a short-lived Node subprocess running an inline TCP probe script that connects to 127.0.0.1:<port> and uses the subprocess exit code to indicate reachability. Tests added validate both success and failure cases with PATH cleared.

Changes

TCP Probe Implementation and Validation

sequenceDiagram
  participant Test
  participant waitForPort
  participant ncShell
  participant NodeProbe
  participant LoopbackServer
  Test->>LoopbackServer: createServer on port
  Test->>waitForPort: call waitForPort(port) with PATH cleared
  alt nc available and numeric status
    waitForPort->>ncShell: run `nc -z 127.0.0.1 <port>`
    ncShell-->>waitForPort: numeric exit status (0/1)
  else nc missing or non-numeric status
    waitForPort->>NodeProbe: spawn `node -e TCP_PROBE_SCRIPT <port>`
    NodeProbe->>LoopbackServer: net.connect 127.0.0.1:port
    LoopbackServer-->>NodeProbe: accept or refuse
    NodeProbe-->>waitForPort: exit 0 (success) or 1 (failure)
  end
  waitForPort-->>Test: return true or false

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

area: networking, bug-fix

Suggested reviewers

• cv

Poem

🐰 I hopped a small script through Node's bright door,
No nc needed on this local shore,
One quick connect, a blink and a cheer,
Ports answered true, or stayed far, my dear —
A tiny rabbit test, and onboarding's clear.

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

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• gpu-repo-local-ollama-openclaw (high): This is the existing scenario that best exercises the impacted real user flow: install/onboard with NEMOCLAW_PROVIDER=ollama, start local Ollama, start the auth proxy through the CLI path that calls waitForPort(), create the sandbox, and verify local inference through the sandbox/proxy route.

Optional E2E

• ollama-proxy-e2e (medium): Useful adjacent confidence for the Ollama auth proxy runtime, token handling, and real inference path, although it starts/probes the proxy from the E2E script rather than directly exercising the CLI waitForPort() readiness gate.
• wsl-repo-cloud-openclaw (high): Optional platform confidence because the fallback was added for nc-missing/Windows-adjacent environments. This scenario validates the WSL install/onboard path, but it does not specifically cover local Ollama auth proxy startup.

New E2E recommendations

• local Ollama auth proxy readiness without nc (medium): Existing E2E coverage does not appear to force PATH to hide nc while running the real CLI onboarding/proxy startup path. The new unit test covers waitForPort() directly, but an E2E regression could still occur in startOllamaAuthProxy() integration.
  • Suggested test: Add a focused regression E2E that starts the real Ollama auth proxy through the CLI/library path with PATH sanitized so nc is unavailable, then asserts readiness succeeds via the Node fallback.

Dispatch hint

• Workflow: .github/workflows/e2e-scenarios.yaml
• jobs input: gpu-repo-local-ollama-openclaw

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• gpu-repo-local-ollama-openclaw: src/lib/core/wait.ts changes waitForPort, which is exercised by the Ollama auth proxy startup path; the only dispatchable scenario covering the ollama-proxy suite is gpu-repo-local-ollama-openclaw.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=gpu-repo-local-ollama-openclaw

Optional scenario E2E

• None.

Relevant changed files

• src/lib/core/wait.ts

• **Runtime validation** — Ollama auth proxy startup detects a listening proxy when nc is unavailable or PATH is empty.. The added unit tests directly cover the utility-level regression and negative path. Because this utility gates Ollama onboarding/runtime readiness, targeted runtime validation would further increase confidence without being required by the diff.
• **Runtime validation** — waitForPort returns false without throwing for invalid, non-integer, NaN, negative, zero, and out-of-range port arguments.. The added unit tests directly cover the utility-level regression and negative path. Because this utility gates Ollama onboarding/runtime readiness, targeted runtime validation would further increase confidence without being required by the diff.
• **Acceptance clause:** Reproduction Steps: "1. Run `nemoclaw onboard`" — add test evidence or identify existing coverage. The changed utility is the one used by Ollama onboarding readiness, and the unit test exercises the missing-nc condition. The PR does not add an end-to-end onboarding test, so this reproduction step is covered indirectly.
• **Acceptance clause:** Reproduction Steps: "2. Select `ollama`" — add test evidence or identify existing coverage. Ollama proxy startup depends on waitForPort, but the added tests target waitForPort directly rather than driving the interactive Ollama onboarding flow.