fix(pairing): complete node bootstrap handoff

[vincentkoc]

Summary

• allow a post-approval hello-ok to move the connection state out of PairingRequired
• avoid storing a node bootstrap handoff token as the operator DeviceToken
• add regression coverage for the state transition and node-role token persistence

Validation

• Local dotnet test blocked: dotnet is not installed on this machine
• Crabbox alpha.13 repro: signed install and node pairing reached pending/approval on desktop2; restart exposed operator token mismatch before this fix
• CI will run required Windows build/test gates on this draft PR

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed May 30, 2026, 5:39 AM ET / 09:39 UTC.

Summary
The branch allows post-approval hello-ok to move the operator out of PairingRequired, prevents node bootstrap handoff tokens from being stored as operator tokens, and adds regression tests for both paths.

Reproducibility: yes. from source inspection: current master rejects HandshakeSucceeded while the operator is PairingRequired, and role-token lookup can fall back to a top-level node deviceToken when looking for an operator token. I did not run a live Windows pairing smoke in this read-only review.

Review metrics: 3 noteworthy metrics.

• Changed Surface: 2 production files, 2 test files. The diff is small but both production files are on the connection and credential pairing path.
• Regression Coverage Added: 3 focused tests added. The new tests cover the state transition plus node-only and operator-handoff token persistence cases.
• Required Local Gates Reported: 0 completed in PR body. Repository policy requires the Windows build plus shared and tray test projects before completion.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Report the required ./build.ps1, shared tests, and tray tests once they run in a suitable Windows/.NET environment.
• [P2] Add or link a redacted setup-code pairing plus tray restart smoke if maintainers want runtime confirmation of the auth handoff.

Mantis proof suggestion
A visible Windows desktop pairing/restart proof would materially reduce auth-handoff risk and no dedicated transport lane fits this PR. A maintainer can ask Mantis to capture proof by posting a new PR comment that starts with the OpenClaw Mantis account mention, followed by:

visual task: verify setup-code node pairing reaches approval, then restart tray and show operator/node reconnect with role-specific tokens redacted.

Risk before merge

• [P1] The PR body reports that local dotnet test was blocked because dotnet is not installed, so the repository-required ./build.ps1, shared tests, and tray tests are not yet reported as completed.
• [P1] The diff changes gateway pairing state and role-specific device-token persistence, so green unit tests alone do not prove the Windows setup-code pairing plus tray restart upgrade path.
• [P1] The PR was still draft and its latest check suite had in-progress jobs at review time, so maintainer validation should wait for the Windows gates and any desired redacted runtime smoke.

Maintainer options:

1. Prove Pairing Restart Before Merge (recommended)
   Run the required Windows gates plus a redacted setup-code node pairing and tray restart smoke that shows operator and node reconnect using role-specific tokens.
2. Accept Unit-Test Coverage Only
   Maintainers may choose to land after CI if they intentionally accept source-level regression coverage without live Windows auth-handoff proof.
3. Hold The Draft For More Evidence
   Pause the draft until runtime proof or maintainer-owned validation confirms the handoff behavior on a signed Windows install.

Next step before merge

• [P2] Maintainers need to confirm required Windows gates and decide whether the auth-handoff proof is sufficient; I did not find a narrow automated repair to queue.

Security
Cleared: The patch touches credential persistence logic but adds no dependency, workflow, permission, secret source, or supply-chain change, and I found no concrete security regression.

Review details

Best possible solution:

Land the focused state-machine and role-token handoff fix after required Windows gates and a redacted setup-code pairing/restart smoke confirm operator and node reconnect with the intended role-specific tokens.

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

Yes from source inspection: current master rejects HandshakeSucceeded while the operator is PairingRequired, and role-token lookup can fall back to a top-level node deviceToken when looking for an operator token. I did not run a live Windows pairing smoke in this read-only review.

Is this the best way to solve the issue?

Yes, the patch is a narrow maintainable fix: it accepts post-approval hello-ok from the pending pairing state and tightens role-token fallback, with focused regression tests. The remaining merge question is validation and runtime proof, not a different implementation direction.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 4351d6a7738f.

Label changes

Label justifications:

• P1: The PR targets a pairing/auth handoff that can leave real Windows node setups stuck after approval or reconnecting with incorrect role-token state.
• merge-risk: 🚨 auth-provider: The diff changes gateway pairing state and role-specific device-token handling, which are credential-sensitive upgrade paths not fully settled by ordinary CI.
• 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 external-contributor proof gate does not apply to this member-authored PR, though a redacted pairing/restart smoke would materially improve maintainer confidence.

Evidence reviewed

What I checked:

• Repository policy applied: AGENTS.md was read fully; its connection/pairing guidance and required validation gates apply because this PR changes gateway pairing, credentials, and tests. (AGENTS.md:34, 4351d6a7738f)
• Architecture boundary: The connection architecture documents PairingRequired lifecycle and strict credential precedence, including the invariant not to downgrade paired devices from stored device tokens to bootstrap/shared tokens. (docs/CONNECTION_ARCHITECTURE.md:96, 4351d6a7738f)
• Current state-machine gap: On current master, HandshakeSucceeded is accepted only from Connecting or Error, so a hello-ok arriving while the operator is still PairingRequired cannot advance the snapshot. (src/OpenClaw.Connection/ConnectionStateMachine.cs:51, 4351d6a7738f)
• Current token fallback gap: On current master, role-token lookup with allowDirectDeviceTokenFallback: false still falls back to the top-level deviceToken when deviceTokens is absent or not an array, which can mis-store a node token as the operator token during node bootstrap handoff. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:2173, 4351d6a7738f)
• PR state-machine fix: At PR head, HandshakeSucceeded explicitly allows RoleConnectionState.PairingRequired, matching the reported post-approval hello-ok flow. (src/OpenClaw.Connection/ConnectionStateMachine.cs:51, f27fd65f94cb)
• PR regression coverage: At PR head, tests cover PairingRequired-to-Connected on HandshakeSucceeded, node-role hello-ok not populating operator token, and operator handoff token storage from deviceTokens. (tests/OpenClaw.Shared.Tests/OpenClawGatewayClientTests.cs:582, f27fd65f94cb)

Likely related people:

• Vincent Koc: Recent merged commits harden Windows node bootstrap reconnects and reconnect-after-approval behavior directly adjacent to this auth handoff path. (role: recent area contributor; confidence: high; commits: 64b650cb3313, 7f19e8109358; files: src/OpenClaw.Shared/OpenClawGatewayClient.cs, src/OpenClaw.Connection/GatewayConnectionManager.cs, tests/OpenClaw.Shared.Tests/OpenClawGatewayClientTests.cs)
• Ranjesh Jaganathan: Introduced the extracted OpenClaw.Connection project and has history on PairingRequired/request-id behavior in the state machine area. (role: connection architecture contributor; confidence: medium; commits: ffeff39c16c5, 8f08a47a5f15; files: src/OpenClaw.Connection/ConnectionStateMachine.cs, src/OpenClaw.Connection/GatewayConnectionManager.cs, tests/OpenClaw.Connection.Tests/ConnectionStateMachineTests.cs)
• Scott Hanselman: Shortlog and recent commits show substantial work in GatewayConnectionManager and adjacent connection reliability tests. (role: recent connection hardening contributor; confidence: medium; commits: 0d4fcbd50ad5; files: src/OpenClaw.Connection/GatewayConnectionManager.cs, tests/OpenClaw.Connection.Tests/GatewayConnectionManagerTests.cs)
• Mike Harsh: Added WSL local gateway onboarding and setup-code flows that overlap the bootstrap pairing handoff path. (role: setup/onboarding feature contributor; confidence: medium; commits: 581f78d276e1; files: src/OpenClaw.Shared/OpenClawGatewayClient.cs, docs/ONBOARDING_WIZARD.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

• 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.