feat: wait for the gateway and report where it is listening

[paulcam206]

Impact

Makes clawctl gateway-service start wait for an owned listener, narrate progress, and report an observed gateway port.

Why This Change Was Made

A launched process is not necessarily a usable gateway. Startup now waits within a bounded, testable budget and reports only an unambiguous observed/configured port. It does not invent an HTTP URL because upstream TLS and Control UI base-path settings are not available here. Status reports a stopped gateway without mislabeling it as a startup failure.

Evidence

Validated at b42b8bc:

• Gateway endpoint/presentation regressions: 14 passed
• .\scripts\Test-DotNetQuality.ps1
• .\scripts\Test-NativeAotCli.Tests.ps1: 17 intended scenarios passed, including gateway narration
• GitHub CI runs on the current head

Installed-package validation was not rerun because this review repair changes host-side endpoint classification and presentation; no local package was deployed.

Stack

1. feat/clawctl json #69 JSON
2. feat: render clawctl help from the live command tree #70 dynamic help
3. feat: report the package and payload build identity from clawctl --version #71 build identity
4. feat: wait for the gateway and report where it is listening #72 narrated gateway startup (this PR)

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs changes before merge. Reviewed September 17, 2026, 11:01 PM ET / September 18, 2026, 03:01 UTC (Revision 5).

ClawSweeper review

What this changes

The Windows launcher waits for the gateway to listen, reports startup progress and an identifiable port, and gives clearer startup-failure guidance.

Merge readiness

⛔ Needs changes before merge - 1 item remains

The bounded startup wait remains useful and is absent from current main and the latest release. Earlier findings are addressed, and no introduced blocking defect was found.

Priority: P2
Reviewed head: b42b8bc056b1505f5cccbdd608d0f7ab84b1088f

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused implementation with relevant regression coverage and no identified blocking defect; real-setup proof is exempt for this collaborator-authored PR.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator exemption applies. Reported tests exercise controller polling with a fake session client and NativeAOT narration, but do not establish an installed gateway startup run; the body explicitly discloses that omission.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The collaborator exemption applies. Reported tests exercise controller polling with a fake session client and NativeAOT narration, but do not establish an installed gateway startup run; the body explicitly discloses that omission.
Evidence reviewed	7 items	Verified review boundary: The checkout matches the pinned PR head. The introduced comparison covers 14 files; the supplied test merge is stale and was not used to infer changes to current main. Current main still inspects once: Main performs one inspection after launch and returns Starting when the process has not bound. It does not implement this PR's listener polling. Latest release comparison: GitHub identifies v2026.9.4-msix.1 as the latest release; its controller also performs a single post-launch inspection.
Findings	None	None.
Security	None	None.

How this fits together

The Windows launcher manages an OpenClaw gateway inside an isolated session. Its gateway controller turns start requests and session observations into lifecycle results, which the CLI renders as human-readable output or JSON.

flowchart TD
  A[Gateway start command] --> B[Prepare owned session]
  B --> C[Launch gateway]
  C --> D[Inspect process and listeners]
  D --> E{Listening or wait finished?}
  E -->|Keep waiting| D
  E -->|Finished| F[Report state and identifiable port]

Loading

Before merge

• Complete next step (P2) - Mark the draft ready before merging and follow the repository's documented bottom-up stack landing order.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	Production +272/-29 lines; tests +640/-8 lines	Production growth supports the stated polling and presentation behavior, with separate coverage for wait outcomes, port classification, and NativeAOT rendering.

Technical review

Best possible solution:

Keep listener readiness in the existing controller and presentation in the CLI, while leaving endpoint configuration and token retrieval to OpenClaw.

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

Not applicable as a feature review; source confirms that main currently returns after one inspection, while the proposed polling paths are covered by focused tests.

Is this the best way to solve the issue?

Yes. Reusing the existing ownership-aware inspection path and renderer is a focused solution, and port-only reporting avoids guessing upstream TLS or Control UI settings.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against b904c90c1439.

Labels

Label justifications:

• P2: This is a bounded improvement to gateway startup feedback and readiness reporting.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The collaborator exemption applies. Reported tests exercise controller polling with a fake session client and NativeAOT narration, but do not establish an installed gateway startup run; the body explicitly discloses that omission.

Evidence

What I checked:

• Verified review boundary: The checkout matches the pinned PR head. The introduced comparison covers 14 files; the supplied test merge is stale and was not used to infer changes to current main. (b42b8bc056b1)
• Current main still inspects once: Main performs one inspection after launch and returns Starting when the process has not bound. It does not implement this PR's listener polling. (src/OpenClaw.Launcher/Gateway/GatewayController.cs:263, b904c90c1439)
• Latest release comparison: GitHub identifies v2026.9.4-msix.1 as the latest release; its controller also performs a single post-launch inspection. (src/OpenClaw.Launcher/Gateway/GatewayController.cs:263, ad5df933da4f)
• Bounded polling preserves ownership checks: The new loop uses the existing inspection client and ownership predicate, exits on observation errors or process disappearance, and passes cancellation through inspection and delays. It does not change authorization, process identity, persisted formats, or launch configuration. (src/OpenClaw.Launcher/Gateway/GatewayController.cs:342, b42b8bc056b1)
• Earlier findings addressed: Current source avoids choosing an arbitrary listener, does not construct runtime URLs, distinguishes stopped status from startup failure, and documents port-only output. Regression tests cover these cases. The earlier reviewed commit was unavailable locally, so no unchanged-code or late-finding attribution is claimed. (tests/OpenClaw.Launcher.Tests/Gateway/GatewayAddressTests.cs:8, b42b8bc056b1)
• Validation scope: The captured PR body reports 14 endpoint/presentation regressions, the .NET quality gate, and 17 NativeAOT scenarios at b42b8bc. The added controller harness uses a fake session client and controlled clock; the NativeAOT scenario exercises rendering. The body explicitly says installed-package validation was not rerun. No tests or target code were executed during this read-only review. (tests/OpenClaw.Launcher.Tests/Gateway/GatewayStartHarness.cs:7, b42b8bc056b1)

Likely related people:

• paulcam206: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (4 earlier review cycles)

• reviewed 2026-09-18T01:10:43.581Z sha 70c4fb5 :: blocked before merge. :: [P2] [P2] Identify the gateway port instead of selecting the lowest listener | [P2] [P2] Respect upstream TLS and Control UI path configuration | [P2] [P2] Limit the startup-exit diagnosis to start results
• reviewed 2026-09-18T01:54:07.945Z sha 9b1fe49 :: needs changes before merge. :: [P3] [P3] Update the startup documentation to match port-only output
• reviewed 2026-09-18T02:09:27.532Z sha c375b56 :: needs changes before merge. :: [P3] [P3] Finish aligning the documentation with port-only output
• reviewed 2026-09-18T02:35:31.182Z sha 674eb68 :: needs maintainer review before merge. :: none