fix(cli): route isPortBusy through checkPortInUse to detect IPv4-only occupants by Pandah97 · Pull Request #94456 · openclaw/openclaw

Pandah97 · 2026-06-18T06:15:40Z

Summary

isPortBusy() in src/cli/ports.ts (the gateway --force kill-port guard) uses a bare tryListenOnPort({ port, exclusive: true }) which binds to the IPv6 wildcard (::) on dual-stack machines. An IPv4-only occupant listening on 127.0.0.1 does not conflict with that bind, so isPortBusy reports the port as free when it is actually taken.

Root cause: Same address-family flaw as #94379. A host-less net.listen binds :: on dual-stack kernels (net.ipv6.bindv6only=0), missing IPv4-only listeners.

Fix: Route isPortBusy through checkPortInUse() (exported from src/infra/ports-inspect.ts) which probes all four endpoints — 127.0.0.1, 0.0.0.0, ::1, :: — instead of a single bare listen. Map its "busy" result to true.

Fixes #94426

Real behavior proof (required for external PRs)

Behavior addressed: isPortBusy() now detects IPv4-only 127.0.0.1 port occupants on dual-stack machines.

Real setup tested:

Runtime: Node v24.13.1 on Linux x86_64 (kernel 4.19.112)
Repository: OpenClaw git worktree at commit 416e2c9432
Verification method: Imported the actual checkPortInUse() function from src/infra/ports-inspect.ts via tsx (TypeScript runtime), created a real IPv4-only net.Server listening on 127.0.0.1, and verified the probe correctly returns "busy". Also verified that free ports return "free".

Exact steps or command run after fix:

import { checkPortInUse } from "./src/infra/ports-inspect.ts";

// Test free port
const freePort = 20000;
const freeStatus = await checkPortInUse(freePort);
// → "free"

// Create IPv4-only listener (the bug scenario)
const server = createServer();
await server.listen(ipv4OnlyPort, "127.0.0.1");
const ipv4Status = await checkPortInUse(ipv4OnlyPort);
// → "busy" — FIX WORKS

After-fix evidence:

=== Real Behavior Proof: PR #94456 ===
Runtime: Node v24.13.1 on linux x64
Repository: OpenClaw worktree (commit 416e2c9432)

=== Test 1: Free port ===
Using free port: 20000
checkPortInUse(20000) = "free" (expected "free")
✅ Free port correctly detected

=== Test 2: IPv4-only listener on 127.0.0.1 (the bug scenario) ===
Creating a server listening ONLY on 127.0.0.1 (IPv4)...
Server listening on 127.0.0.1:21000
checkPortInUse(21000) = "busy" (expected "busy")
✅ IPv4-only listener DETECTED (the fix works!)

Before/after comparison:

Scenario	Old behavior (hostless bind)	New behavior (checkPortInUse)
Free port	correct	correct
IPv4-only 127.0.0.1:PORT	FALSE FREE — old code binds `::` which does not conflict with `127.0.0.1`	BUSY ✅ — probes all 4 endpoints

What was not tested: Exhaustive matrix of all possible port states. The three outcomes ("free", "busy", "unknown") are exercised by the existing unit test suite (23 tests across 3 files). The live socket test above covers the specific bug scenario: an IPv4-only 127.0.0.1 listener that the old hostless bind would miss.

Tests and validation

All 23 port-related tests pass across 3 test files. Additionally verified with a live IPv4-only 127.0.0.1 socket that the probe correctly returns "busy".

Risk checklist

Did user-visible behavior change? (Yes)

gateway --force now correctly detects IPv4-only port occupants instead of missing them

Did config, environment, or migration behavior change? (No)

Did security, auth, secrets, network, or tool execution behavior change? (No)

What is the highest-risk area?

checkPortInUse returns "unknown" when all four probes fail with non-EADDRINUSE errors (edge case); isPortBusy throws for this case, same as the old code threw for non-EADDRINUSE errors

How is that risk mitigated?

All existing port tests pass with the new implementation
The checkPortInUse function was already thoroughly tested in fix(ports): probe all address families in ensurePortAvailable #94415 (13 tests)
Live socket verification confirms the fix works for the reported scenario

Current review state

What is the next action?

Maintainer review

Which bot or reviewer comments were addressed?

ClawSweeper: needs real behavior proof from a real setup with live IPv4-only listener (P1)

… occupants - Export checkPortInUse from src/infra/ports-inspect.ts - Replace bare tryListenOnPort in isPortBusy with checkPortInUse which probes all four endpoints (127.0.0.1, 0.0.0.0, ::1, ::) - Previously a host-less listen only bound to IPv6 wildcard (::), missing IPv4-only 127.0.0.1 occupants on dual-stack machines Fixes openclaw#94426

clawsweeper · 2026-06-18T09:50:48Z

Thanks for the context here. I swept through the related work, and this is now duplicate or superseded.

Close: this useful CLI bug-fix branch is now superseded by the focused, proof-positive sibling at #94949, while this PR duplicates the current main probe helper shape and carries unrelated agent/provider cherry-pick files.

Canonical path: Land the focused sibling #94949 as the canonical fix, then close this duplicate branch and the linked issue after that PR merges.

So I’m closing this here and keeping the remaining discussion on #94949.

Review details

Best possible solution:

Land the focused sibling #94949 as the canonical fix, then close this duplicate branch and the linked issue after that PR merges.

Do we have a high-confidence way to reproduce the issue?

Yes. Current main still uses a hostless isPortBusy bind and forceFreePortAndWait exits early on a false-free result; I did not run a live socket reproduction in this read-only review.

Is this the best way to solve the issue?

No for this branch as the landing path. Reusing a shared multi-endpoint probe is the right fix, but current main's owner is now probePortUsage and #94949 implements that cleaner path with proof.

Security review:

Security review cleared: The diff adds no dependency, workflow, secret, permission, package, or supply-chain surface; the security pass found no concrete concern.

AGENTS.md: found and applied where relevant.

What I checked:

Current main still has the reported bug shape: isPortBusy on current main still calls tryListenOnPort({ port, exclusive: true }) without a host, so the central gateway --force issue is real and not implemented on main. (src/cli/ports.ts:133, 6834a2d47bbf)
Caller can exit before cleanup: forceFreePortAndWait returns immediately when isPortBusy reports false, so a false-free port probe bypasses listener lookup and cleanup. (src/cli/ports.ts:278, 6834a2d47bbf)
Current main already has the shared four-host probe under a different owner: Current main exposes the all-address-family probe as probePortUsage in src/infra/ports-probe.ts, returning busy, unknown, or free after probing 127.0.0.1, 0.0.0.0, ::1, and ::. (src/infra/ports-probe.ts:52, 6834a2d47bbf)
This branch reintroduces the older helper surface: The PR head exports checkPortInUse from ports-inspect.ts and uses it from isPortBusy, duplicating the current-main probePortUsage owner instead of rebasing onto it. (src/infra/ports-inspect.ts:637, 416e2c943270)
Superseding PR uses the current-main helper and preserves unknown handling: The open sibling at fix(ports): route isPortBusy through checkPortInUse to catch IPv4-only occupants #94949 changes isPortBusy to use probePortUsage(port) !== "free" and adds focused force-port test coverage for the unknown path. (src/cli/ports.ts:139, 9072d1e3522f)
Superseding PR has positive review/proof signals: Live PR metadata for fix(ports): route isPortBusy through checkPortInUse to catch IPv4-only occupants #94949 shows proof: sufficient, status: 👀 ready for maintainer look, and successful Real behavior proof, check-lint, and check-test-types checks on head 9072d1e3522fe90d9a50373664ebb4e7339efd3b. (9072d1e3522f)

Likely related people:

steipete: git log -S forceFreePortAndWait and file stats show Peter Steinberger introduced the retrying gateway --force helper and later hardened the same src/cli/ports.ts path. (role: introduced and hardened gateway force-port behavior; confidence: high; commits: 0b4e70e38b92, 39f7dbfe02ce; files: src/cli/ports.ts, src/cli/program.force.test.ts)
Vincent Koc: Current blame and history show Vincent Koc carrying the current snapshot of isPortBusy, probePortUsage, and inspectPortUsage in the central port files. (role: recent area contributor; confidence: medium; commits: 9e6332338855, c645ec4555c0; files: src/cli/ports.ts, src/infra/ports-probe.ts, src/infra/ports-inspect.ts)
Pandah97: The PR author also appears in merged current-main history for the adjacent Browser/CDP address-family preflight fix, which shares the same port-probe invariant on a different surface. (role: adjacent sibling-fix author; confidence: medium; commits: 4ec9d4a2b511; files: src/infra/ports.ts, src/infra/ports.test.ts, extensions/browser/src/browser/chrome.ts)
ajay99511: A recent merged change credited Ajay for Windows-compatible port detection in the same gateway force-port helper area. (role: adjacent platform contributor; confidence: medium; commits: e23b6fb2ba75; files: src/cli/ports.ts, src/cli/program.force.test.ts)

Codex review notes: model internal, reasoning high; reviewed against 6834a2d47bbf.

Cherry-pick from main to fix pre-existing test failure in openai-transport-stream where tools are expected to have strict:true but code on this branch produces strict:false.

Pandah97 · 2026-06-22T14:48:33Z

CI fixes

Fixed 2 of 4 failing CI checks:

check-lint — typescript(consistent-return) in src/cli/ports.ts: Added default: return false case to isPortBusy switch statement to ensure all code paths return a value.
checks-node-agentic-agents-core-models — Pre-existing test mismatch in openai-transport-stream.test.ts:5293: Cherry-picked commit c50899275e from main which adds strict: true support for projected OpenAI tools.

Remaining failures (check-test-types, checks-node-core-src-security) are pre-existing and unrelated to this PR's changes.

Pandah97 · 2026-06-23T07:14:33Z

@clawsweeper re-review

clawsweeper · 2026-06-23T07:14:36Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

clawsweeper · 2026-06-23T13:52:17Z

ClawSweeper applied the proposed close for this PR.

Action: closed this PR.
Close reason: duplicate or superseded.
Evidence: durable ClawSweeper review.
Coverage proof: PR B clearly carries PR A's core useful behavior and review concerns for the isPortBusy/IPv4-only port detection bug, while PR A's remaining differences are either incidental proof/context or unrelated carry-along changes that should not keep PR A open. Covering PR: fix(ports): route isPortBusy through checkPortInUse to catch IPv4-only occupants #94949.

openclaw-barnacle Bot added cli CLI command changes size: XS proof: supplied External PR includes structured after-fix real behavior proof. labels Jun 18, 2026

This was referenced Jun 18, 2026

isPortBusy preflight misses IPv4-only occupant (same address-family flaw as #94379) #94426

Closed

fix(cli): isPortBusy probes all 4 address families to catch IPv4-only listeners #94469

Closed

fix(cli): add IPv4 loopback host to isPortBusy #94448

Closed

This was referenced Jun 18, 2026

fix(ports): probe all address families in ensurePortAvailable #94415

Closed

fix: #94426 isPortBusy probes all address families via checkPortInUse #94471

Closed

sunlit-deng mentioned this pull request Jun 19, 2026

fix(ports): route isPortBusy through checkPortInUse to catch IPv4-only occupants #94949

Merged

clawsweeper Bot mentioned this pull request Jun 19, 2026

fix: isPortBusy preflight misses IPv4-only occupant #94463

Closed

vincentkoc and others added 2 commits June 22, 2026 22:47

fix(agents): keep strict mode for projected OpenAI tools

0e15872

fix(agents): keep strict mode for projected OpenAI tools

416e2c9

Cherry-pick from main to fix pre-existing test failure in openai-transport-stream where tools are expected to have strict:true but code on this branch produces strict:false.

openclaw-barnacle Bot added agents Agent runtime and tooling size: S and removed size: XS labels Jun 22, 2026

clawsweeper Bot closed this Jun 23, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(cli): route isPortBusy through checkPortInUse to detect IPv4-only occupants#94456

fix(cli): route isPortBusy through checkPortInUse to detect IPv4-only occupants#94456
Pandah97 wants to merge 3 commits into
openclaw:mainfrom
Pandah97:fix/issue-94426-isportbusy-ipv4-occupant

Pandah97 commented Jun 18, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 18, 2026 •

edited

Loading

Uh oh!

Pandah97 commented Jun 22, 2026

Uh oh!

Pandah97 commented Jun 23, 2026

Uh oh!

clawsweeper Bot commented Jun 23, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

Pandah97 commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Real behavior proof (required for external PRs)

Tests and validation

Risk checklist

Current review state

Uh oh!

clawsweeper Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Pandah97 commented Jun 22, 2026

CI fixes

Uh oh!

Pandah97 commented Jun 23, 2026

Uh oh!

clawsweeper Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

clawsweeper Bot commented Jun 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Pandah97 commented Jun 18, 2026 •

edited

Loading

clawsweeper Bot commented Jun 18, 2026 •

edited

Loading

clawsweeper Bot commented Jun 23, 2026 •

edited

Loading