fix(server): wait for canonical muxcore health

[thebtf]

Summary

Close the successor-startup native-health gap exposed by muxcore v0.28 timing:

• wait boundedly for MuxEngine.Ready() before selecting the status source;
• prefer in-process daemon status once published;
• use Aimux's stored canonical eng.ControlSocketPath() for control fallback instead of recomputing from the display engine name;
• preserve the existing normalized native field contract on both sessions(action=health) and aimux://health.

Regression tests

• canonical socket path wins when namespace differs from display name;
• canceled request returns immediately while the engine is pre-ready;
• existing native status normalization remains intact.

Evidence

• RED: focused tests initially failed to compile because health attachment was not context-aware (artifact://3085).
• GREEN: go test ./pkg/server -run '^(TestAttachNativeMuxcoreHealth_|TestQueryNativeStatusAt_)' -count=20 -timeout 300s (artifact://3088).
• go build ./... PASS.
• Rebased on merged SQLite fixture isolation 24575a4; go test ./... -count=1 -timeout 600s PASS, 57 packages (artifact://3110).

Scope boundary

This PR fixes the independent native-health readiness/path defect. It does not claim to fix muxcore lifecycle callback ordering. v5.24.2 remains blocked on Engram mcp-mux #405 and a corrective provider tag before the counted Aimux Phase A cutover is implemented.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 30 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f79c4ef8-315e-4c0a-ba9a-444399757725

📥 Commits

Reviewing files that changed from the base of the PR and between 24575a4 and 783583e.

📒 Files selected for processing (2)

• pkg/server/f2_metrics_test.go
• pkg/server/server.go

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/v5242-native-health-readiness

---

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

[thebtf]

@coderabbitai review focus:successor startup readiness, canonical control path, bounded wait, schema compatibility files:pkg/server/server.go,pkg/server/f2_metrics_test.go

[thebtf]

@codex review

[thebtf]

@codex review

[thebtf]

@gemini-code-assist review focus:context-blind behavioral acceptance for successor startup health

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '=== Scoped diff ==='
git diff --unified=80 "$(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD HEAD~1)" HEAD -- \
  pkg/server/server.go pkg/server/f2_metrics_test.go || true

echo '=== Requested file outlines ==='
ast-grep outline pkg/server/server.go --items all --type function,method --match 'Health|health|Native|native|Status|status|Ready|ready|Attach|attach|Query|query' || true
ast-grep outline pkg/server/f2_metrics_test.go --items all --type function,method --match 'Health|health|Native|native|Status|status|Ready|ready|Attach|attach|Query|query' || true

echo '=== Relevant definitions and call sites ==='
rg -n -C 8 -P '\b(AttachNativeMuxcoreHealth|QueryNativeStatusAt|ControlSocketPath|MuxEngine|Ready|sessions|aimux://health)\b' \
  pkg/server --glob '*.go' || true

echo '=== Go module muxcore dependency ==='
rg -n -C 2 'muxcore' go.mod go.sum 2>/dev/null || true

Length of output: 179139

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '=== Native status helpers ==='
ast-grep outline pkg/server/f2_metrics.go --items all --type function,method --match 'Native|native|Status|status|Normalize|normalize|Query|query' || true
rg -n -C 35 -P 'func\s+(normalizeNativeStatus|queryNativeStatus(?:At)?|queryF2Metrics(?:At)?)\b' \
  pkg/server/f2_metrics.go pkg/server/*.go || true

echo '=== Daemon accessor and engine/socket wiring ==='
rg -n -C 18 -P 'func\s+\(s\s+\*Server\)\s+(liveDaemon|SetMuxEngine|SetDaemonControlSocketPath)\b|\.(SetMuxEngine|SetDaemonControlSocketPath)\s*\(|ControlSocketPath\s*\(' \
  --glob '*.go' . || true

echo '=== Health resource/tool regression coverage ==='
rg -n -C 10 -P 'func\s+Test.*(Health|NativeStatus|NativeMuxcore|HealthResource|SessionsHealth)\b|attachNativeMuxcoreHealth\s*\(' \
  pkg/server --glob '*_test.go' || true

echo '=== Dependency source API shape (if vendored/module cache exists) ==='
fd -a 'engine.go|daemon.go' "$(go env GOPATH 2>/dev/null)/pkg/mod/github.com/thebtf/mcp-mux" 2>/dev/null \
  | head -30 \
  | xargs -r -n1 sh -c 'echo "--- $0"; rg -n -C 8 -P "func\s+\(.*MuxEngine.*\)\s+(Ready|Daemon|ControlSocketPath)\b" "$0" || true' || true

Length of output: 37263

---

@thebtf No findings in the requested scope.

The change correctly:

• waits up to five seconds for MuxEngine.Ready() and respects cancellation during that startup wait;
• prefers MuxEngine.Daemon().HandleStatus() after readiness;
• falls back through the stored daemonControlSocketPath, populated from eng.ControlSocketPath(), rather than deriving it from the display name;
• applies the same normalizeNativeStatus contract to both in-process and socket-derived status;
• propagates request context from both sessions(action="health") and aimux://health.

The added regression tests cover the canonical-path mismatch and cancellation-before-ready behavior.

[gemini-code-assist]

Code Review

This pull request updates the attachNativeMuxcoreHealth method to accept a context and wait for the mux engine to be ready before querying its status, utilizing a new waitForMuxEngineReady helper. It also updates the status query to use the daemon control socket path if available and adds corresponding unit tests. The reviewer pointed out an issue in waitForMuxEngineReady where context cancellation is not checked in the initial non-blocking select block, which could lead to unnecessary downstream I/O if the context is already canceled.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Code Review

This pull request updates the server's health check mechanism to support context-aware waiting for the native muxcore engine's readiness and allows querying status from a specific daemon control socket path. New unit tests have been added to verify these behaviors. The review feedback correctly identifies an issue in waitForMuxEngineReady where a timeout on the readiness wait returns nil instead of an error, which would incorrectly signal that the engine is ready and lead to a futile socket query.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: ae4162aa07

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".