fix(gateway): honor minimal discovery mode for wide-area DNS-SD [AI]

[pgondhi987]

Summary

• Problem: Wide-area DNS-SD publishing used a separately resolved CLI path instead of the discovery-mode-filtered value.
• Why it matters: Operators using reduced discovery metadata should get consistent TXT record contents across discovery transports.
• What changed: The wide-area zone writer now receives the same filtered cliPath value already prepared by gateway discovery startup.
• What did NOT change (scope boundary): TXT rendering, domain resolution, tailnet address selection, and full discovery mode behavior are unchanged.

AI-assisted: Yes

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• N/A
• This PR addresses a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: Wide-area DNS-SD should follow minimal discovery metadata filtering for CLI path publication.
• Real environment tested: Not run in this metadata drafting step.
• Exact steps or command run after this patch: Not run in this metadata drafting step.
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): Unit regression coverage was added in src/gateway/server-discovery-runtime.test.ts; execution not performed here.
• Observed result after fix: Code inspection shows writeWideAreaGatewayZone now receives the already-filtered cliPath value.
• What was not tested: Live gateway startup and generated zone output.
• Before evidence (optional but encouraged): Existing runtime path passed a fresh CLI path resolution into wide-area zone writing.

Root Cause (if applicable)

• Root cause: Gateway discovery startup computed a mode-filtered cliPath, but the wide-area publishing branch bypassed that value and resolved the CLI path again.
• Missing detection / guardrail: No runtime-level test asserted minimal-mode wide-area zone parameters.
• Contributing context (if known): Local discovery advertisement already used the filtered context value, so the divergence was isolated to wide-area zone writing.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/server-discovery-runtime.test.ts
• Scenario the test should lock in: With wide-area discovery enabled and mdnsMode: "minimal", gateway startup writes the wide-area zone without a cliPath value and does not resolve the CLI path.
• Why this is the smallest reliable guardrail: The behavior is decided in gateway discovery startup before zone rendering, so the mocked runtime test covers the branch directly.
• Existing test that already covers this (if any): None.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

In minimal discovery mode, wide-area DNS-SD TXT records no longer include the OpenClaw CLI path. Full discovery mode behavior is unchanged.

Diagram (if applicable)

Before:
minimal discovery mode -> wide-area zone write -> fresh CLI path resolution -> TXT includes cliPath

After:
minimal discovery mode -> filtered cliPath value -> wide-area zone write -> TXT omits cliPath

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Not run in this metadata drafting step
• Runtime/container: Not run in this metadata drafting step
• Model/provider: N/A
• Integration/channel (if any): Gateway discovery
• Relevant config (redacted): discovery.wideArea.enabled=true, discovery.mdns.mode=minimal

Steps

1. Configure gateway wide-area discovery with minimal discovery metadata.
2. Start gateway discovery with a tailnet IPv4 address available.
3. Inspect the generated wide-area DNS-SD TXT record.

Expected

• The TXT record does not include cliPath when minimal discovery metadata is active.

Actual

• After this patch, the wide-area writer receives cliPath: undefined in the minimal-mode regression test setup.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: Read the changed runtime path and regression test setup.
• Edge cases checked: Confirmed full mode still resolves and passes cliPath through the existing filtered variable; minimal mode keeps it undefined.
• What you did not verify: Did not run the test suite or a live gateway environment in this metadata drafting step.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: Full discovery mode could stop publishing CLI path if the filtered value is not preserved.
  • Mitigation: The implementation reuses the existing cliPath variable, which is populated only for full mode and already used for local discovery context.

[clawsweeper]

Codex review: needs real behavior proof before merge.

Summary
This PR passes the filtered gateway discovery cliPath into wide-area DNS-SD zone writing, adds a minimal-mode regression test, and updates Bonjour/wide-area discovery docs.

Reproducibility: yes. source-level reproduction is high-confidence: on current main with wide-area discovery enabled and mdnsMode: "minimal", cliPath is filtered to undefined but the wide-area writer re-resolves it before zone rendering. I did not run a live gateway or inspect a generated zone file.

Real behavior proof
Needs real behavior proof before merge: The PR body says no real environment or command was run after the patch; unit coverage and code inspection are useful but are not real behavior proof for an external PR. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, ask a maintainer to comment @clawsweeper re-review.

Next step before merge
Needs contributor-provided real behavior proof and a small docs consistency pass before normal maintainer review; this is not a ClawSweeper repair-lane candidate because the main blocker is external proof from the contributor's setup.

Security
Cleared: The diff narrows published discovery metadata and does not add dependencies, permissions, secrets handling, CI, or new command/network execution paths.

Review findings

• [P3] Keep gateway discovery docs consistent — docs/cli/gateway.md:521

Review details

Best possible solution:

Land the focused runtime change after the contributor adds real behavior proof and the remaining discovery docs are made consistent with the new wide-area TXT filtering behavior.

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

Yes, source-level reproduction is high-confidence: on current main with wide-area discovery enabled and mdnsMode: "minimal", cliPath is filtered to undefined but the wide-area writer re-resolves it before zone rendering. I did not run a live gateway or inspect a generated zone file.

Is this the best way to solve the issue?

Yes, reusing the existing filtered cliPath is the narrowest maintainable fix because it keeps local and wide-area discovery on the same prepared metadata path. The safer follow-up is docs consistency, not a broader discovery refactor.

Full review comments:

• [P3] Keep gateway discovery docs consistent — docs/cli/gateway.md:521
  This section still says only gateways with Bonjour discovery enabled advertise the beacon, but this PR now documents and implements that wide-area DNS-SD can publish a minimal Gateway beacon when discovery.mdns.mode is off and discovery.wideArea.enabled is true. Please update this sentence and the parallel /gateway/discovery TXT hint text so operators do not think wide-area publishing requires Bonjour LAN advertising or always writes cliPath.
  Confidence: 0.84

Overall correctness: patch is correct
Overall confidence: 0.84

Acceptance criteria:

• pnpm test src/gateway/server-discovery-runtime.test.ts
• git diff --check

What I checked:

• Current main source path: startGatewayDiscovery computes cliPath from mdnsMode at startup, but current main still calls resolveBonjourCliPath() again when writing the wide-area zone, so minimal/off filtering is bypassed for cliPath. (src/gateway/server-discovery-runtime.ts:172, 842cadda260a)
• Existing config contract: The configuration reference says minimal discovery omits cliPath and sshPort from TXT records, which supports treating the wide-area cliPath divergence as a bug rather than a new feature. Public docs: docs/gateway/configuration-reference.md. (docs/gateway/configuration-reference.md:789, 842cadda260a)
• PR patch evidence: The PR patch changes the wide-area call from cliPath: resolveBonjourCliPath() to cliPath and adds a unit test asserting minimal-mode wide-area zone parameters omit cliPath and do not resolve the CLI path. (src/gateway/server-discovery-runtime.ts:172, 95d3f9b864fd)
• Remaining docs inconsistency: Current docs still say wide-area DNS-SD writes cliPath as a remote-install hint, and the live PR file list shows this page is not changed by the branch. Public docs: docs/gateway/discovery.md. (docs/gateway/discovery.md:77, 842cadda260a)
• Live PR state and labels: The live PR is open, mergeable, authored by a contributor, and carries the protected maintainer label, so this cleanup review should not close it. (95d3f9b864fd)
• Feature history: GitHub file history for gateway discovery and wide-area DNS files points to recent and repeated work by steipete, the Bonjour plugin move by vincentkoc, and the mDNS minimal-mode security config by orlyjamie. (src/gateway/server-discovery-runtime.ts, 57a3d7f6e897)

Likely related people:

• steipete: Recent history shows repeated gateway discovery, Bonjour, and wide-area DNS-SD work, including the discovery runtime timeout fix and wide-area DNS helper refactor. (role: recent area contributor; confidence: high; commits: 57a3d7f6e897, e51a00ffc77f, ee6052a1691b; files: src/gateway/server-discovery-runtime.ts, src/infra/widearea-dns.ts, docs/gateway/bonjour.md)
• vincentkoc: History shows the Bonjour discovery plugin move and nearby docs maintenance on the affected discovery documentation surface. (role: adjacent owner; confidence: medium; commits: cb4fc585472a, 0d73f174a942, 7a3955168572; files: src/gateway/server-discovery-runtime.ts, docs/gateway/bonjour.md, docs/gateway/discovery.md)
• orlyjamie: History identifies this account on the commit that added mDNS discovery config to reduce information disclosure, which is the policy this PR is applying to wide-area cliPath. (role: feature introducer; confidence: medium; commits: a1f9825d6313; files: src/gateway/server-discovery-runtime.ts)

Remaining risk / open question:

• The contributor has not supplied real after-fix proof from a gateway or generated wide-area DNS-SD zone; the PR body explicitly says it was not run in a real environment.
• Docs are still not fully consistent: at least docs/gateway/discovery.md and a sentence in docs/cli/gateway.md can still imply wide-area publishing requires or always includes Bonjour metadata.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 842cadda260a.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/25715465765
• Updated: 2026-05-12T05:40:10.344Z

[pgondhi987]

Not applicable to this automation stage; changelog/release-note and external real behavior proof requirements are handled outside auto-pr stages.

Quoted comment from @clawsweeper:

Codex review: needs real behavior proof before merge.

Summary
This PR passes the filtered gateway discovery cliPath into wide-area DNS-SD zone writing, adds a minimal-mode regression test, and updates Bonjour/wide-area discovery docs.

Reproducibility: yes. source-level reproduction is high-confidence: on current main with wide-area discovery enabled and mdnsMode: "minimal", cliPath is filtered to undefined but the wide-area writer re-resolves it before zone rendering. I did not run a live gateway or inspect a generated zone file.

Real behavior proof
Needs real behavior proof before merge: The PR body says no real environment or command was run after the patch; unit coverage and code inspection are useful but are not real behavior proof for an external PR. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, ask a maintainer to comment @clawsweeper re-review.

Next step before merge
Needs contributor-provided real behavior proof and a small docs consistency pass before normal maintainer review; this is not a ClawSweeper repair-lane candidate because the main blocker is external proof from the contributor's setup.

Security
Cleared: The diff narrows published discovery metadata and does not add dependencies, permissions, secrets handling, CI, or new command/network execution paths.

Review findings

• [P3] Keep gateway discovery docs consistent — docs/cli/gateway.md:521

Review details

Best possible solution:

Land the focused runtime change after the contributor adds real behavior proof and the remaining discovery docs are made consistent with the new wide-area TXT filtering behavior.

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

Yes, source-level reproduction is high-confidence: on current main with wide-area discovery enabled and mdnsMode: "minimal", cliPath is filtered to undefined but the wide-area writer re-resolves it before zone rendering. I did not run a live gateway or inspect a generated zone file.

Is this the best way to solve the issue?

Yes, reusing the existing filtered cliPath is the narrowest maintainable fix because it keeps local and wide-area discovery on the same prepared metadata path. The safer follow-up is docs consistency, not a broader discovery refactor.

Full review comments:

• [P3] Keep gateway discovery docs consistent — docs/cli/gateway.md:521
  This section still says only gateways with Bonjour discovery enabled advertise the beacon, but this PR now documents and implements that wide-area DNS-SD can publish a minimal Gateway beacon when discovery.mdns.mode is off and discovery.wideArea.enabled is true. Please update this sentence and the parallel /gateway/discovery TXT hint text so operators do not think wide-area publishing requires Bonjour LAN advertising or always writes cliPath.
  Confidence: 0.84

Overall correctness: patch is correct
Overall confidence: 0.84

Acceptance criteria:

• pnpm test src/gateway/server-discovery-runtime.test.ts
• git diff --check

What I checked:

• Current main source path: startGatewayDiscovery computes cliPath from mdnsMode at startup, but current main still calls resolveBonjourCliPath() again when writing the wide-area zone, so minimal/off filtering is bypassed for cliPath. (src/gateway/server-discovery-runtime.ts:172, 842cadda260a)
• Existing config contract: The configuration reference says minimal discovery omits cliPath and sshPort from TXT records, which supports treating the wide-area cliPath divergence as a bug rather than a new feature. Public docs: docs/gateway/configuration-reference.md. (docs/gateway/configuration-reference.md:789, 842cadda260a)
• PR patch evidence: The PR patch changes the wide-area call from cliPath: resolveBonjourCliPath() to cliPath and adds a unit test asserting minimal-mode wide-area zone parameters omit cliPath and do not resolve the CLI path. (src/gateway/server-discovery-runtime.ts:172, 95d3f9b864fd)
• Remaining docs inconsistency: Current docs still say wide-area DNS-SD writes cliPath as a remote-install hint, and the live PR file list shows this page is not changed by the branch. Public docs: docs/gateway/discovery.md. (docs/gateway/discovery.md:77, 842cadda260a)
• Live PR state and labels: The live PR is open, mergeable, authored by a contributor, and carries the protected maintainer label, so this cleanup review should not close it. (95d3f9b864fd)
• Feature history: GitHub file history for gateway discovery and wide-area DNS files points to recent and repeated work by steipete, the Bonjour plugin move by vincentkoc, and the mDNS minimal-mode security config by orlyjamie. (src/gateway/server-discovery-runtime.ts, 57a3d7f6e897)

Likely related people:

• steipete: Recent history shows repeated gateway discovery, Bonjour, and wide-area DNS-SD work, including the discovery runtime timeout fix and wide-area DNS helper refactor. (role: recent area contributor; confidence: high; commits: 57a3d7f6e897, e51a00ffc77f, ee6052a1691b; files: src/gateway/server-discovery-runtime.ts, src/infra/widearea-dns.ts, docs/gateway/bonjour.md)
• vincentkoc: History shows the Bonjour discovery plugin move and nearby docs maintenance on the affected discovery documentation surface. (role: adjacent owner; confidence: medium; commits: cb4fc585472a, 0d73f174a942, 7a3955168572; files: src/gateway/server-discovery-runtime.ts, docs/gateway/bonjour.md, docs/gateway/discovery.md)
• orlyjamie: History identifies this account on the commit that added mDNS discovery config to reduce information disclosure, which is the policy this PR is applying to wide-area cliPath. (role: feature introducer; confidence: medium; commits: a1f9825d6313; files: src/gateway/server-discovery-runtime.ts)

Remaining risk / open question:

• The contributor has not supplied real after-fix proof from a gateway or generated wide-area DNS-SD zone; the PR body explicitly says it was not run in a real environment.
• Docs are still not fully consistent: at least docs/gateway/discovery.md and a sentence in docs/cli/gateway.md can still imply wide-area publishing requires or always includes Bonjour metadata.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 842cadda260a.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/25728934995
• Updated: 2026-05-12T10:35:59.068Z