fix: discover listening ports on macOS

[nicodes]

Fixes https://github.com/nicodes/ormos-be/issues/289

Part of epic https://github.com/nicodes/ormos-be/issues/493

Risk: high — listening-service discovery is disclosed to the relay and participates in the port-exposure boundary.

Summary

• keep the established Linux /proc/net/tcp* parser behind a Linux helper
• discover Darwin IPv4 and IPv6 TCP listeners with bounded base-system /usr/sbin/netstat -anl -f <family> calls
• accept only documented LISTEN rows bound to loopback or wildcard addresses, with deterministic deduplication and ordering
• fail explicitly on command, timeout, output-bound, and malformed-schema errors; relay disclosure fails closed and TUI polling keeps its last-good snapshot
• run the real loopback-listener policy test on macOS instead of skipping

Darwin mechanism and constraints

Apple Darwin netstat(1) source/manpage at version network_cmds-596.100.2 documents -a, -n, -f inet|inet6, lowercase -l, local/foreign address output, wildcard *, and LISTEN: https://github.com/apple-oss-distributions/network_cmds/blob/network_cmds-596.100.2/netstat.tproj/netstat.1. Go 1.25 supports macOS 12+: https://go.dev/doc/go1.25#darwin. The implementation uses the absolute base-system path and does not assume lsof.

The manpage documents semantic columns but not a machine-readable stable schema. Parsing therefore validates the documented header and listener shape and treats unrecognized/malformed output as an error. Its synopsis makes -f and -p alternatives, so the code intentionally selects each family with -f and filters tcp4/tcp6 rows itself rather than combining flags undocumentedly. A shared 2-second context bounds both family calls, each command has a 250ms WaitDelay, and stdout/stderr are drained into 1 MiB capped buffers.

Verification

• mise exec -- go version → go1.25.13 linux/amd64
• mise exec -- go test -race -count=1 ./...
• mise exec -- govulncheck ./... → no reachable vulnerabilities
• go vet ./...
• CI platform-selection gate reproduced locally: unsupported targets select relay only; Linux and Darwin builds succeed
• deterministic Darwin parser source-list test: mise exec -- go test -count=1 internal/system/ports_darwin.go internal/system/ports_darwin_test.go

Local Linux runs do not exercise the Darwin command integration. The macOS exact-head CI job must prove the real ephemeral listener and policy assertions.

Deliberate failure proof

Changed the deterministic expected result from [4100, 4200, 4300] to [4101, 4200, 4300], then ran mise exec -- go test -count=1 internal/system/ports_darwin.go internal/system/ports_darwin_test.go. It failed with: discoverDarwinPorts() = [4100 4200 4300], want [4101 4200 4300]. The mutation was reverted and the identical command passed.
The real ephemeral-listener gate was also mutated from Port to Port + 1 and pushed. Exact-head macOS run https://github.com/nicodes/ormos/actions/runs/32661759428 failed under go test -race -count=1 ./... with: ports_test.go:57: with no policy the listing should contain the test listener :49205 (got [49204]). Linux failed analogously. The mutation was restored in commit d4ee8f9; the focused local test passed before push.

Review remediation

Initial aggregate: #69 (comment). Commit 97d6aa5 (rebased equivalent of a29498f) accepts whitespace-only successful family output while preserving errors for nonempty malformed output, adds the empty-IPv6/valid-IPv4 fixture, and corrects the stale README statement.

The new assertion was deliberately changed from [4100] to [4101]. mise exec -- go test -count=1 internal/system/ports_darwin.go internal/system/ports_darwin_test.go failed with TestDiscoverDarwinPortsKeepsOtherFamilyWhenOneIsEmpty: discoverDarwinPorts() = [4100], want [4101]; the mutation was reverted and the identical command passed. Full Go 1.25.13 race tests, vet, govulncheck, platform-selection/build checks, and exact-head Linux/Darwin CI passed.

gh stack sync replayed the four commits onto origin/main at 6b3acae676d0b6ff24020cd0f3697ef4538d48a2; stable patch IDs before and after sync both equal 5336098fec29cd241f7a52c58c7b023c792a4cb0, confirming the PR diff was unchanged by the rebase. Final review head is 97d6aa5585d29b2731895a53ff7abb242164eb27; green CI run: https://github.com/nicodes/ormos/actions/runs/32665564761.

[nicodes]

Review 1A

BLOCKING — internal/system/ports_darwin.go:37-46, 104-139 rejects a valid empty address-family scan. Apple’s netstat source prints the Proto header only after finding a socket row; thus a Mac with an IPv4 loopback listener but no inet6 sockets causes the valid inet6 output to lack a header, returning an error and discarding the discovered IPv4 port. handleListPorts then discloses [], and polling retains stale state. The established Linux control independently tolerates an absent/empty /proc/net/tcp6 while preserving IPv4 results (ports_linux.go:16-25). Accept an empty family result as zero listeners, while retaining explicit failure for nonempty unrecognized/malformed output; add a fixture proving IPv4 discovery succeeds when the inet6 runner returns empty output.

FOLLOW-UP — README.md:39-40 still says live port status is Linux-only and macOS never marks ports live. This PR implements the opposite behavior. Update the supported-platform documentation to describe Darwin base-system netstat discovery and its failure behavior.

Review method: confirmed pinned HEAD d4ee8f9ca352c42b5afe90fd4f8b0b05be53eb7d and clean worktree; inspected the complete six-file pinned diff (+356/-95), traced list-port and TUI-poll call paths, and compared against the Linux parser control. Reviewed Go 1.25 and Apple network_cmds-596.100.2 documentation/source. Verified exact-head green actionlint, Linux CI, and Darwin CI metadata; ran go test -race -count=1 ./... locally on Linux (passed). The documented deliberate parser and real-listener gate failures establish those assertions are reachable. Residual risk: local execution could not exercise Darwin, so Darwin evidence is limited to the exact-head CI run.

NEEDS ATTENTION

[nicodes]

Review 1B

INCOMPLETE — required reviewer reviewer-kimi-k3-256k could not start because its billing-cycle usage limit is exhausted. Verbatim tool result:

Subagent failed (task_id: ses_fcfd92476ffethga80bBCih1FY): You've reached your usage limit for this billing cycle. Your quota will be refreshed in the next cycle. To continue now, purchase extra usage or upgrade your plan: https://www.kimi.com/code/#pricing

No substitute reviewer was used because the dispatch explicitly requires Kimi K3-256K. No remediation has started; the initial high-risk wave remains incomplete on unchanged head d4ee8f9ca352c42b5afe90fd4f8b0b05be53eb7d.

INCOMPLETE

[nicodes]

Initial review-wave aggregate

The wave is incomplete and blocked: Review 1A reported one BLOCKING defect (valid empty family output is rejected) and one FOLLOW-UP (stale README platform statement); Review 1B could not execute because the explicitly required Kimi K3-256K reviewer exhausted its billing-cycle quota.

Per the high-risk review-wave policy, no code or documentation edits will be made until every initial slot completes on the same unchanged head. The findings therefore remain undispositioned pending completion of Review 1B. No sensitive content was present or redacted.

[nicodes]

Replacement Review 1B

Review 1B (replacement) — PR 69, initial wave

Risk: high — listener discovery is disclosed to the relay and sits on the port-exposure boundary.

Pinned range reviewed: c86552e77fad9b8d0f568a043682704bb159fd21...d4ee8f9ca352c42b5afe90fd4f8b0b05be53eb7d
Confirmed HEAD: d4ee8f9ca352c42b5afe90fd4f8b0b05be53eb7d (matches pinned head; worktree clean).
Diff inspected: complete six-file triple-dot diff (+356/-95), not the last commit. Files: ports.go, ports_darwin.go, ports_darwin_test.go, ports_linux.go, ports_test.go, system.go.
Method: independent read of the full pinned diff and current files; control comparison of the Linux parser against the base listeningPorts/scanProcNet/isLoopbackOrWildcard; caller/policy trace through handleListPorts, proxyAllowed, pollPorts, and KindListPorts; versioned Apple netstat.1 at network_cmds-596.100.2 plus Go 1.25 Darwin notes. Did not read any other reviewer. Did not run tests (read-only; this host is not Darwin). Explorer research was treated as source pointers and re-checked against the fetched manpage.

Limitation: this is the replacement 1B slot after a Kimi K3-256K quota blocker. Same model family as other grok reviewers; isolated context only.

---

Findings

FOLLOW-UP — README still claims live port status is Linux-only

README.md:39-41 still says:

Live port status is a Linux-only feature for now: the agent finds listening ports by reading /proc/net/tcp, so on macOS the dashboard shows configured ports without marking which are up.

This PR removes that gap. Darwin listeningPorts() now shells out to /usr/sbin/netstat and handleListPorts will disclose the policy-filtered set to the relay. The old shared comment in base ports.go even pointed at this README sentence as the documented macOS hole.

Concrete scenario: a macOS operator who last read the supported-platforms section still believes the relay cannot learn which loopback/wildcard services are up. After this head, KindListPorts returns the same filtered listing Linux already returned.

This is not a code or policy-boundary defect. It is a published false claim about the exact surface this PR changes.

Acceptance: in the default-repo README supported-platforms section, delete or rewrite the Linux-only live-status paragraph so it states that Linux and macOS both report TCP LISTEN ports bound to loopback or wildcard, and that the listing is filtered through policy.proxyAllowed before relay disclosure.

---

No BLOCKING or BLOCKING TEST GAP findings.

The Darwin command matches the versioned manpage: -a shows server sockets, -n keeps numeric host.port, -l is “Print full IPv6 address” (not listen-only; listen queues are -L), -f inet/inet6 are the documented family filter, and the synopsis treats -f and -p as alternatives. Parser checks require the Proto/Recv-Q/Send-Q header, fields[3] as local, last field LISTEN, and a closed host allowlist. Linux /proc parser and best-effort empty-on-read-failure behavior are a verbatim move. handleListPorts still applies proxyAllowed before encoding; discovery errors are logged, audited as denied (Allowed: false), and encoded as [] rather than returned as a successful empty scan. TestListPortsFilteredThroughPolicy no longer skips on Darwin, so the ephemeral loopback listener must appear with no policy and must disappear under deniedPorts / authoritative allowedPorts. Parser fixtures have exact-slice and exact-error assertions.

Residual risks (not defects)

• Darwin CI is macos-latest, not the Go 1.25 floor (macOS 12). Field order for -anl is unchanged from Monterey-era network_cmds-624 through current sources; this review did not execute netstat on macOS 12.
• Darwin never prints 0.0.0.0 / :: for unspecified (it prints *). Those allowlist entries are inert. Non-.1 127/8 and IPv4-mapped ::ffff:127.0.0.1 stay excluded, matching the Linux hex allowlist.
• netstat -a dumps the full socket table; a host that exceeds the 1 MiB / 2 s bounds fails closed (relay sees [], TUI keeps last-good). That is bounded, not silent.
• Local TUI live highlighting still uses the unfiltered listen cache. Relay disclosure is the filtered path. That split is pre-existing on Linux.

APPROVE

[nicodes]

Initial review-wave aggregate (replacement 1B complete)

The main orchestrator selected reviewer-grok-4.6 as the independent replacement after durable verification of the genuine Kimi K3-256K quota blocker. The prior Review 1B INCOMPLETE comment remains preserved.

Deduplicated findings

1. BLOCKING — accept valid empty address-family output. Terra 1A found that netstat may emit no header when a selected family has no sockets. Current parsing treats that successful empty result as malformed and discards listeners found in the other family. Remediation: accept whitespace-only family output as zero listeners, retain explicit errors for nonempty unrecognized/malformed output, and add a fixture proving IPv4 results survive empty IPv6 output.
2. FOLLOW-UP — stale README Linux-only statement. Both reviewers identified the published statement that macOS cannot show live ports. Remediation disposition: fix it in this PR, describing Linux/macOS loopback-or-wildcard TCP LISTEN discovery and policy filtering before relay disclosure; no follow-up issue will remain if the correction is complete.

Wave verdicts

• Terra Review 1A: NEEDS ATTENTION
• Replacement Grok Review 1B: APPROVE

Both findings are accepted. They will be remediated together in one batch, then exact-head checks will run before both original reviewer contexts review the full history and remediation delta. No sensitive content was present or redacted.

[nicodes]

Final Review 1A

No findings.

Prior BLOCKING resolved: parseDarwinNetstat now accepts whitespace-only output without clearing prior-family results, while nonempty unrecognized output still errors (internal/system/ports_darwin.go:104-143). The new reachable Darwin fixture preserves IPv4 port 4100 when inet6 is empty (ports_darwin_test.go:39-57); the supplied mutation failure proves this assertion can fail.

Prior FOLLOW-UP resolved: README now accurately describes Linux/macOS listener discovery and policy filtering (README.md:39-43).

Reviewed the complete current 7-file diff and remediation deltas a29498f^..a29498f / 97d6aa5^..97d6aa5; no new material regressions found. Confirmed final HEAD 97d6aa5585d29b2731895a53ff7abb242164eb27, clean worktree, and green exact-head actionlint/Linux/Darwin checks. Ran go test -race -count=1 ./... locally on Linux: passed. Darwin runtime coverage remains evidenced by the exact-head macOS CI run.

APPROVE

[nicodes]

Final Replacement Review 1B

Review 1B (replacement) — PR 69, final remediation

Risk: high — listener discovery is disclosed to the relay and sits on the port-exposure boundary.

Final range: 6b3acae676d0b6ff24020cd0f3697ef4538d48a2...97d6aa5585d29b2731895a53ff7abb242164eb27
Confirmed HEAD: 97d6aa5585d29b2731895a53ff7abb242164eb27
Prior reviewed head: d4ee8f9ca352c42b5afe90fd4f8b0b05be53eb7d
Method: read-only confirmation of HEAD; complete current triple-dot diff (7 files); remediation delta 97d6aa5^..97d6aa5; content diff of the previously reviewed non-remediation files against d4ee8f9; re-read parseDarwinNetstat, the new test, and the README paragraph; checked Monterey-era network_cmds-624.100.5 protopr for empty-family stdout. Did not relitigate unchanged code. Did not read other reviewer write-ups beyond the dispositions supplied here.

ports.go, ports_linux.go, ports_test.go, and system.go are byte-identical to the head I already approved. Remediation is only README.md, ports_darwin.go (+4/-1), and ports_darwin_test.go (+20).

---

Prior dispositions

My FOLLOW-UP (stale Linux-only README) — resolved.
README.md:39-42 now states that Linux and macOS both report TCP listeners bound to loopback or wildcard, names the two discovery mechanisms, and says the listing is filtered through the same local port policy that governs proxy connections before relay disclosure. That matches the acceptance I wrote.

Terra BLOCKING (valid empty family discarded the other family) — resolved.
parseDarwinNetstat (ports_darwin.go:107-140) now requires the documented header only when a non-whitespace line was seen. Whitespace-only / empty successful output returns nil and leaves the other family's ports in the set.

Apple protopr prints the title and Proto Recv-Q Send-Q header only after a matching PCB survives the family filter; if len <= sizeof(struct xinpgen) or every PCB is skipped, it returns with no stdout. Empty family output is therefore a real -f inet / -f inet6 shape, not a synthetic edge. The new test feeds inet a 127.0.0.1.4100 LISTEN row and inet6 "\n", and requires [4100]. The reported mutation [4100] → [4101] failed with discoverDarwinPorts() = [4100], want [4101], then passed after revert. Nonempty garbage still errors: TestDiscoverDarwinPortsFailuresAreExplicit / malformed output still expects missing documented socket table header for "not a socket table\n".

Policy filtering, Linux /proc behavior, and the fail-closed tool/timeout/malformed paths are untouched.

---

No BLOCKING, BLOCKING TEST GAP, or remaining FOLLOW-UP findings.

No new material regression in the remediation: empty success is no longer treated as malformed; nonempty unrecognized output still fails the whole discovery; relay disclosure is still proxyAllowed-filtered.

Residual risk, unchanged from the initial review: Darwin CI is macos-latest, not the macOS 12 floor. Empty-family handling is now source-backed and fixture-tested; this review did not run netstat.

APPROVE

[nicodes]

Final review aggregate

Both required reviewer contexts approve exact head 97d6aa5585d29b2731895a53ff7abb242164eb27 after inspecting the full history and remediation delta.

• Terra 1A: prior empty-family BLOCKING resolved; README FOLLOW-UP resolved; APPROVE.
• Replacement Grok 1B: prior README FOLLOW-UP resolved; verified Terra blocker remediation; APPROVE.

All findings are dispositioned. No BLOCKING, BLOCKING TEST GAP, or still-applicable FOLLOW-UP remains, so no follow-up issue is required before merge. Exact-head actionlint, Linux CI, and Darwin CI are green. No sensitive content was present or redacted.

[nicodes]

Post-review rebase delta

A merge attempt was rejected because main had advanced and required checks were expected on the updated base. gh stack sync rebased onto 35aa236c69ff41bff86feb02667161ac673f1105, which includes PR #70 and its relay-output gate. That newly landed gate reached this PR's local discovery-error log and exact-head CI correctly failed with relay output gate: system.go:270: pollPorts relay-derived dynamic value reaches a terminal output without sanitizeRelayOutput or the explicit %q allowlist on run https://github.com/nicodes/ormos/actions/runs/32667708744.

The owned log statement now uses the gate's explicit %q allowlist for the local netstat error. Focused TestRelayDerivedOutputGate, full Go 1.25.13 race tests, and vet passed locally. Exact-head actionlint/Linux/Darwin CI is green on 5fc840661f8709efcf6fdb089cbf7bae9f53ebd0: https://github.com/nicodes/ormos/actions/runs/32667829868. The changed head invalidates prior approvals, so both reviewer contexts will inspect the complete current diff and this one-line integration delta before merge.

[nicodes]

Post-rebase Final Review 1A

No findings.

The rebase preserves both prior remediations: empty Darwin family output retains the other family’s ports with a reachable fixture, and the README accurately documents macOS discovery. The integration delta is limited to quoting local discovery errors with %q at internal/system/system.go:270; this escapes terminal-control characters without changing discovery, policy filtering, or relay disclosure behavior. The base’s relay-output sanitization remains intact.

Reviewed the complete 7-file current diff, 5fc8406^..5fc8406, and the base gate integration. Confirmed final HEAD 5fc840661f8709efcf6fdb089cbf7bae9f53ebd0, clean worktree, and green exact-head actionlint/Linux/Darwin checks. Ran go test -race -count=1 ./... and go vet ./... locally on Linux: passed. Darwin runtime evidence remains the exact-head CI job.

APPROVE

[nicodes]

Post-rebase Final Replacement Review 1B

Review 1B (replacement) — PR 69, post-rebase integration

Risk: high — listener discovery is disclosed to the relay and sits on the port-exposure boundary.

Final range: 35aa236c69ff41bff86feb02667161ac673f1105...5fc840661f8709efcf6fdb089cbf7bae9f53ebd0
Confirmed HEAD: 5fc840661f8709efcf6fdb089cbf7bae9f53ebd0
Prior approved head: 97d6aa5585d29b2731895a53ff7abb242164eb27
Method: read-only HEAD check; complete current triple-dot diff (same 7 files); content diff of those files against 97d6aa5; integration commit 5fc8406^..5fc8406; re-read pollPorts, handleListPorts, parseDarwinNetstat, README, and base TestRelayDerivedOutputGate. Did not relitigate unchanged discovery/policy code.

The only owned delta since the last approval is system.go:270: d.logf("ports discovery failed: %q", err). Other system.go differences versus 97d6aa5 (echoWriter, sanitized ports poll failed) are on the new base from PR #70, not this PR.

---

Prior dispositions

README FOLLOW-UP — still resolved. README.md:39-42 still documents Linux/macOS loopback-or-wildcard TCP LISTEN reporting and proxyAllowed filtering before relay disclosure.

Terra empty-family BLOCKING — still resolved. parseDarwinNetstat still requires a header only when sawContent is set (ports_darwin.go:107-140). TestDiscoverDarwinPortsKeepsOtherFamilyWhenOneIsEmpty is still in the tree.

Integration change

Base TestRelayDerivedOutputGate inspects every logf in pollPorts and accepts only literals, sanitizeRelayOutput(...), or a %q verb (relay_output_gate_test.go:70-77, 266-288). After the rebase, local discovery’s %v failed that block (run 32667708744). %q is the gate’s explicit allowlist; for this path it also quotes netstat/parse text before it reaches the log ring / headless echo. Discovery control flow, last-good TUI cache, and handleListPorts policy filtering are unchanged.

handleListPorts still logs list ports discovery: %v (ports.go:27). That site is outside the gate’s bounded pollPorts inspection, was on the previously approved head, and is not a new regression.

---

No BLOCKING, BLOCKING TEST GAP, or remaining FOLLOW-UP findings.

No material regression: the rebase-only fix satisfies the new static gate without widening relay disclosure or weakening empty-family / malformed handling.

APPROVE

[nicodes]

Post-rebase final review aggregate

Both required reviewer contexts approve exact head 5fc840661f8709efcf6fdb089cbf7bae9f53ebd0 after inspecting the complete current diff, durable review history, rebase integration, and the one-line %q gate fix. All prior findings remain resolved. No BLOCKING, BLOCKING TEST GAP, or applicable FOLLOW-UP remains; no follow-up issue is required. Exact-head actionlint, Linux CI, and Darwin CI are green. No sensitive content was present or redacted.