[MertBasar0]

What Problem This Solves

Fixes the generic “Gateway connection check failed.” message when an existing Gateway recognizes the client but requires device approval.

User Impact

Setup now displays the existing “Gateway authentication failed or device approval is required.” hint for a recognized pairing-required response. Check remains unsuccessful, and Next stays on connection setup without saving the connection or approving the device.

The internal PairingRequired classification is not forwarded in the UI-facing SetupNativeConnectionResult. The shared message still does not distinguish an invalid token from pending approval. This change does not add a request ID, approval command or automatic approval.

Why This Change Was Made

The shared client raises PairingRequired before the transport closes, but the setup validator did not handle that event. Handling it through the existing first-result-wins completion preserves the pairing classification and approval-aware message; the existing cleanup removes the event handler.

The patch contains five production lines and 48 regression-test lines. It preserves the current successful-handshake requirement rather than treating pending pairing as success.

Historical behavior and related work

Historical comparison: #201 (feat: add setup wizard with pairing-aware connection test) treated pending pairing as a successful reachability check, with approval instructions. That branch remained until the old wizard was removed in #925 (feat: add Windows gateway onboarding wizard). Today’s separate validator was introduced in #1531 (feat: guide Windows onboarding from setup to native AI tasks) without pairing-event handling; its introduction and pinned-base blobs are identical. This is a diagnostic parity gap in a replacement path, not a demonstrated in-place regression. Current documented/tested semantics require a ready operator, so the patch deliberately does not copy #201’s success semantics. The historical comparison is source-reviewed; earlier acceptance plans have been superseded by the completed observations below.

Related, not exact duplicates: #1704 reports token mismatch/no pending requests; #1796 (fix: keep Gateway setup validation errors visible) changes layout visibility; #1858 (fix: node pairing rejection reports success when Gateway denies it) and #1859 (fix: keep device pairing pending until Gateway acknowledgement) change acknowledgement of later pairing decisions.

Evidence

A native Windows client connected to a separate real WSL Gateway, followed by manual baseline/patched wizard checks in fresh profiles:

Scenario	Baseline	Patched
Pairing required	Gateway connection check failed.	Gateway authentication failed or device approval is required.
Wrong token	Existing authentication/approval message	Same message; protocol logs identify token mismatch
Ordinary disconnect	Generic connection-check error	Same generic error

All 12 Check/Next observations are complete. Next stayed on setup, settings hashes were unchanged, no Gateway registry or persistent identity was committed, and no devices were paired. Pairing/authentication used the real test Gateway; ordinary disconnect used an explicitly labeled WebSocket-close fixture.

Before: pairing-required Check

After: pairing-required Check

These are developer-supplied manual screenshots with different capture dimensions. They demonstrate functional messages, not controlled DPI/layout parity. The baseline derivative removes only unrelated pixels outside the app; the original is preserved and the derivative is hash-mapped. Retained-pixel equality was reported by Codex, not independently rerun by Roboclaw.

Sanitized Windows action/state/protocol records and Shared diagnostic analysis are retained locally. The two images above are public GitHub attachments; anonymous downloads return the inspected PNG bytes with matching SHA-256 hashes. No full evidence archive is published.

Human contribution: Mert Başar supplied the scenario and performed the manual Windows wizard checks. Codex executed/collected Windows validation; Roboclaw implemented the patch and reconciled the evidence. No pairing approval is part of this change.

Change Type

• Bug fix
• Feature
• Refactor
• Docs or instructions
• Tests or validation
• Security hardening
• Chore or infrastructure

Scope

• Tray or WinUI UX
• Windows node capability
• Local MCP or winnode
• Gateway, connection, or pairing
• Setup or onboarding
• Permissions, privacy, or security
• Tests, CI, or docs

Required proof pools

• windows-wsl-gateway-e2e: existing-Gateway pairing diagnostic. Real Windows-to-WSL rejection and no-commit behavior were observed; the formal inventory-owned pool was not executed.
• windows-winui-interactive: visible setup diagnostic. All 12 manual functional observations are complete; formal pool execution and HWND/desktop/DPI-bound capture remain unverified.

These declarations do not claim completed pool proof. The separate desktop/job protected the automated Tray suite only; manual wizard actions used the normal interactive desktop with isolated profiles and task TEMP.

Validation

Tested source: ed1444b0de69957ff9af6e2fd9998b591b5854ce plus the unchanged, uncommitted two-file patch. Patch SHA-256: 2e688ccc5322b5d9db5157d1ef1901763c07f9b93baf19e367b67c277eb24436.

Recorded native Windows commands and results are below. The task runner supplied isolated app/state roots and C: task TEMP; the Tray command ran on a separate noninteractive desktop with an owned process job. These are retained execution results, not new runs from this document review.

Recorded command	Result
.\build.ps1 -NoTrustRepository	Both baseline and patched full Windows/WinUI builds passed
dotnet test .\tests\OpenClaw.Connection.Tests\OpenClaw.Connection.Tests.csproj --filter FullyQualifiedName~Handshake_PreservesPairingRequiredAcrossTerminalStatus --logger 'trx;LogFileName=baseline.trx' --results-directory $results	Unpatched production: 2 expected pairing failures, 2 controls passed
dotnet test .\tests\OpenClaw.Connection.Tests\OpenClaw.Connection.Tests.csproj --filter FullyQualifiedName~GatewayConnectionValidatorTests --logger 'trx;LogFileName=validator.trx' --results-directory $results	Patched: 32 passed, 0 failed/skipped
dotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --logger 'trx;LogFileName=tray.trx' --results-directory $results --blame-hang --blame-hang-timeout 5m --blame-hang-dump-type none	4,561 passed, 0 failed/skipped; includes 53 direct-connect cases
dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --logger 'trx;LogFileName=shared.trx' --results-directory $results --blame-hang --blame-hang-timeout 5m --blame-hang-dump-type none	4,646 passed, 2 failed, 26 skipped

All 155 earlier Linux Tray failures were matched by test name and passed on Windows. The earlier Linux reports remain historical evidence. The initial validator ACL failure on E: was retained and diagnosed separately; the final isolated C: TEMP run passed 32/32 without changing machine security settings.

Shared is not green. The hostname test compares the NetBIOS machine name with the longer system-hostname output on this host; its assertion already ignores case. The symbolic-link fixture fails with Windows error 1314 before production admission; native symlink coverage remains unverified. The unchanged Shared DLL and lack of a Connection dependency support non-attribution to this patch. These failures are explained, not fixed or waived.

Windows builds, tests and runtime observations were executed/collected by Codex with Mert operating the wizard. During local publication preparation on October 28, Codex directly reopened the original Windows build/TRX records and verified counts and candidate-source correspondence. Robo inspected the UI archive and Shared diagnostic addendum. These reviews are not new Windows executions; original build/TRX files remain private local evidence.

Independent review: the canonical Auto Review helper completed a P0–P3 local review against the pinned base with the full validator, regression and unchanged parser/transport/UI context: scoped-clean, no findings. A separate read-only Codex subagent reviewed implementation/proof-plan fit and the original native receipts, source/binary correspondence and manual observations, with no actionable P0–P3 findings. No product suites were rerun during publication preparation. Earlier narrative reviews and Linux failures remain historical evidence.

Real Behavior Proof

• Environment tested: Windows 11 x64 build 26200.9457, .NET SDK 10.0.402; separate WSL Gateway 2026.9.1; synthetic test credentials and fresh app profiles.
• PR head: b3f157e8fc2a5ef2a68c38f19be7892a211200f6. Native tests ran earlier against pinned base ed1444b0de69957ff9af6e2fd9998b591b5854ce plus the patch recorded above. This commit has the identical complete candidate tree 6505062ad3e384a08843e2ea33891464dfdb739d; the commit itself was not a new test run. Canonical full-index patch SHA-256: 1771f30a432870bb1ada00da64b7cc5af01b9a64ee767b7346652d382e8e7e9c.
• Exact steps or command run: launch preserved baseline/patched apps in separate fresh profiles; connect to the test Gateway and perform Check then Next. Repeat with an invalid token, then with the labeled ordinary-disconnect fixture. Compare action logs, settings/registry/identity state and pairing inventories.
• Evidence after fix: the patched pairing Check and Next show the approval-aware message; the real client retains GatewayErrorKind.PairingRequired. Wrong-token results remain Auth; ordinary-disconnect results remain generic failures.
• Observed result: 12 completed manual observations, no advance or committed state and no automatic approval. Owned test apps/listeners were stopped; preservation checks for existing installations passed.
• Screenshot or artifact links verified? Yes. Both embedded GitHub attachments resolve anonymously as PNG files matching the inspected hashes. Other reports remain local, not public artifact links.
• Not verified or blocked: formal proof-pool runs, HWND/desktop/DPI-bound capture, successful paired chat/reconnection, and the original installed-app incident's pending-request identities. Shared retains two explained failures and 26 skips. Successful Computer Use is not claimed.

Security Impact

• New permissions or capabilities? No
• Secrets or tokens handling changed? No
• New or changed network calls? No
• Command or tool execution surface changed? No
• Data access scope changed? No
• If any answer is Yes, explain the risk and mitigation: N/A.

Compatibility and Migration

• Backward compatible? Yes
• Config or environment changes? No
• Migration needed? No
• If yes, list the exact upgrade steps: N/A.

Review Conversations

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

[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: blocked before merge.

What this changes

This PR shows the existing device-approval hint when Gateway setup receives a pairing-required response.

Example: Check connection to ws://127.0.0.1:29671 while the Windows device awaits Gateway approval.

• Before: Gateway connection check failed.
• After: Gateway authentication failed or device approval is required.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	Strong visible proof supports a focused correct repair; the broader recovery request remains partial, and hosted validation has not run.
Proof confidence	🦞 diamond lobster (5/6) ✨ media proof bonus	Sufficient (screenshot): Inspected native setup screenshots show the changed validator message before and after the patch; the PR ties the identical candidate tree to Windows 11 checks against WSL Gateway 2026.9.1 and reports Check/Next remaining unsuccessful without committed state. Formal pool completion and successful pairing are not claimed.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Bug fix · Worth it: Yes · Fix scope: Partial
User problem: A reachable Gateway awaiting device approval appears as a generic connection-check failure during setup.
Reason: The small repair provides useful diagnostic parity without weakening readiness checks; it covers only part of the broader approval-guidance report and should not close that report.

Merge readiness

⛔ Blocked before merge - 1 item remains

Keep open: this PR fixes a current diagnostic gap with a focused, correct change and visible before/after proof; hosted validation awaits approval.

Priority: P2
Reviewed head: b3f157e8fc2a5ef2a68c38f19be7892a211200f6

Before merge

• Await maintainer action - Review and approve the action-required Build and Test and CodeQL workflow runs for this PR.

Findings

None.

Tests

• Missing end-to-end proof: No missing shipped-path scenario blocks this diagnostic change; the PR reports base-failing/head-passing cases, while hosted Build and Test and CodeQL have not executed.

Agent review details

How this fits together

The one-shot connection validator converts Gateway client events into setup results, which the native setup host displays before allowing a connection transaction.

flowchart TD
  A[Setup connection form] --> B[Native connection host]
  B --> C[Connection validator]
  C --> D[Gateway client]
  D --> E[Gateway pairing response]
  E --> C
  C --> F[Failed check with approval hint]
  F --> A

Loading

Technical review

Best possible solution:

Land the focused diagnostic repair after validation, keeping the broader actionable approval experience tracked separately.

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

Current-main source shows PairingRequired bypassing authentication-failure handling before disconnect produces the generic error; supplied screenshots show the before/after behavior, but this review ran no reproduction.

Is this the best way to solve the issue?

The event subscription is the smallest complete fix for the stated diagnostic gap, preserving first-result-wins failure semantics and symmetric cleanup without adding another owner.

AGENTS.md: found and applied where relevant.

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

Provenance checked

• One-shot setup validation keeps the original intent (3eed1f1: Merged onboarding work established isolated checks, staged identity and successful operator authentication before advancing.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

• Exact introduced change: The pinned introduction adds only the pairing event handler, subscription and cleanup, plus the focused regression theory. (src/OpenClaw.Connection/GatewayConnectionValidator.cs:172, b3f157e8fc2a)
• Current main still needs the fix: Current main subscribes to handshake, authentication failure and terminal status, but omits PairingRequired; the shared client emits that event without AuthenticationFailed. (src/OpenClaw.Connection/GatewayConnectionValidator.cs:178, 326884ed0510)
• Save and approval boundaries preserved: Native Next returns on unsuccessful validation before disconnecting the previous connection or promoting identity state; setup documentation explicitly excludes pairing-pending from successful operator readiness. (src/OpenClaw.Tray.WinUI/Services/GatewayDirectConnectService.cs:122, b3f157e8fc2a)
• Inspected visible proof: The current PR's before and after attachments visibly show the generic error changing to the approval-aware hint. Mert Başar supplied the manual Windows observations against a separate WSL Gateway. Prepared manifest images showed other setup states, so the current attachments were fetched and inspected directly. (b3f157e8fc2a)
• Feature history and original intent: Merged feat: guide Windows onboarding from setup to native AI tasks #1531 established isolated validation and ready-operator semantics; the earlier reachability-success approach in feat: add setup wizard with pairing-aware connection test #201 is historical context, not the current contract. (src/OpenClaw.Connection/GatewayConnectionValidator.cs:164, 3eed1f1bac56)
• Broader report remains distinct: [UX] Setup shows generic Gateway connection failure when device pairing approval is pending #1904 requests specific pending-approval guidance, request identification and approval instructions; this PR addresses the lost diagnostic but does not deliver that complete recovery experience.

Review metrics

Metric	Value	Why it matters
Focused change size	Production +5 lines; tests +48 lines	Reuses the existing completion and cleanup owners; the theory protects pairing precedence over both terminal statuses and ordinary-disconnect controls.

Labels

Label changes:

• add P2: A narrow setup diagnostic improvement helps users recognize pending approval while preserving the required approval boundary.
• add proof: sufficient: Contributor real behavior proof is sufficient.
• add proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• add status: ⏳ waiting on maintainer: Only explicit maintainer approvals or decisions remain; merge is still blocked.

Label justifications:

• P2: A narrow setup diagnostic improvement helps users recognize pending approval while preserving the required approval boundary.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: ⏳ waiting on maintainer: Only explicit maintainer approvals or decisions remain; merge is still blocked.
• proof: sufficient: Contributor real behavior proof is sufficient.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence.

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Obtain completed Build and Test and CodeQL results for the reviewed head.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 28, 2026, 12:39 PM ET / 16:39 UTC.

[shanselman]

Thanks, Mert, for the clear reproduction and detailed Windows evidence. I’m a Copilot triage agent, not Scott. I reviewed this change with three independent reviewers and added a small maintainer follow-up so a slow WebSocket close cannot replace the pairing hint. The updated head passed the CI Gate.