feat(setup): guide channel readiness handoff

[clawsweeper]

Summary

• distinguish a connected Gateway and paired Windows device from mobile/chat channel readiness on setup completion
• let users finish directly into Channels through a typed post-setup destination while preserving existing owners
• make the gateway-host plugin handoff explain why terminal use is required, give the exact copyable command, state the expected result, and provide return-to-app verification
• document the boundary and add focused setup/tray contract coverage

Addresses #1156.
Contributes to #843.

Validation

• git diff --check: passed before commit
• autoreview --mode local --stream-engine-output: clean, no accepted/actionable findings (confidence 0.93)
• build.ps1, Shared tests, Tray tests, and SetupEngine tests: not run, blocked before sync because this Linux controller has no dotnet/PowerShell and Crabbox could not establish SSH to three native Windows desktop leases

Crabbox attempts:

• Azure / windows / normal / desktop / blue-hermit-8666: lease ended before SSH became usable
• Azure / windows / normal / desktop / golden-krill: lease ended before SSH became usable
• AWS broker / windows / normal / desktop / jade-krill: SSH endpoint was never populated or reachable

CI remains required for the automated suites at this head.

Real behavior proof

Not verified / blocked. No Crabbox native Windows lease reached source sync, so current-head isolated setup and visible completion-to-Channels proof could not be captured. Before readiness, a current-head Windows run must show:

1. setup completion with Gateway/device readiness separate from the channel card
2. Set up or verify channels restarts into Channels
3. a non-running channel exposes the copyable gateway-host plugin command, expected result, and Refresh guidance

Ownership and safety

• SetupWindow continues to own setup completion and startup preference persistence.
• App remains the composition/restart owner and routes only the typed destination.
• ChannelsPage remains the owner of Gateway channel state and verification.
• No channel command is inferred or automated, no parallel Gateway client is created, and no credentials are logged or displayed.

Review

• Rubber-duck/source review traced success, failure, default Chat, Channels, restart, and single-instance forwarding paths.
• Structured autoreview was clean; no findings were accepted or rejected.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

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

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 13, 2026, 4:28 PM ET / 20:28 UTC.

ClawSweeper review

What this changes

The PR adds a setup-completion route to Channels and clearer guidance for installing and verifying gateway-hosted channel plugins.

Merge readiness

⛔ Blocked until real behavior proof is added - 3 items remain

Keep open. The supplied PR diff directly addresses the active, member-authored channel-handoff requirement, but the PR explicitly lacks current-head native Windows behavior proof and the required local validation was not run. Likely related people: RomneyDa for the narrowed requirement and samanthamsong for the broader onboarding epic, both low-confidence routing signals because local history inspection was blocked.

Priority: P2
Reviewed head: 6a3cb68de4d86b942db50c548dc4d96adbfcc8d2

Review scores

Measure	Result	What it means
Overall readiness	🧂 unranked krab (1/6)	The scoped patch and automated checks look credible from the supplied context, but missing real native Windows proof is a merge gate.
Proof confidence	🧂 unranked krab (1/6)	Needs real behavior proof before merge: The PR explicitly reports that no current-head native Windows setup run was captured; CI and source-contract tests are supplemental, not proof of this WinUI flow. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The PR explicitly reports that no current-head native Windows setup run was captured; CI and source-contract tests are supplemental, not proof of this WinUI flow. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	6 items	Active canonical requirement: The related open issue explicitly requires separating Gateway connection from channel readiness and providing an exact terminal handoff with expected result and return-to-app verification. Proposed implementation: The supplied PR diff adds a typed Channels completion destination, routes the restarted tray into Channels, and expands the gateway-host plugin guidance. Missing real behavior proof: The PR body states “Not verified / blocked” and provides no current-head native Windows run showing completion, Channels navigation, and channel refresh after plugin installation.
Findings	None	None.
Security	None	None.

How this fits together

Setup completion restarts the Windows tray application into a selected surface. This change carries a Channels destination from onboarding to the tray, where the existing channel page shows Gateway-reported status and a guided plugin-install handoff.

flowchart LR
A[Setup completion] --> B[Choose Chat or Channels]
B --> C[Tray restart]
C --> D[Channels surface]
D --> E[Gateway channel status]
E --> F[Guided plugin handoff]

Loading

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The PR explicitly reports that no current-head native Windows setup run was captured; CI and source-contract tests are supplemental, not proof of this WinUI flow. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve merge risk (P1) - The changed native Windows setup path has not been observed at the current PR head, and local source/history inspection was blocked by the sandbox before it could independently validate the full implementation.
• Complete next step (P2) - No discrete repair is identified from the supplied diff; the remaining merge blocker is contributor-provided native Windows proof and required validation.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Changed surface	8 files, +90/-10 lines	The handoff spans setup UI, tray restart routing, channel copy, documentation, and contract coverage.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #1156
Summary: This PR is a candidate implementation of the concrete guided terminal-handoff requirement; the broader onboarding epic overlaps but remains distinct.

Members:

• canonical: Guide terminal-required setup and channel configuration instead of leaving dead ends #1156 - Its definition of done specifically calls for the readiness distinction, exact terminal handoff, and return-to-app verification implemented here.
• partial_overlap: First-run experience — default onboarding into the local gateway #843 - It tracks the broader local-gateway onboarding outcome, while this PR targets the narrower channel handoff seam.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Capture a redacted current-head native Windows run of the three documented handoff steps, report the required validation from a Windows host, then continue normal PR review.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Capture a redacted current-head native Windows run of the three documented handoff steps, report the required validation from a Windows host, then continue normal PR review.

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

Not applicable as a bug reproduction: this PR adds a guided UX path. Its required after-fix native Windows proof is currently absent.

Is this the best way to solve the issue?

Yes, conditionally. Carrying a typed destination while retaining Channels as the Gateway-status owner is a narrow solution, but it needs a real current-head Windows demonstration before merge.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against bc518f7bd158.

Labels

Label changes:

• add P2: This is a bounded first-run and channel-setup usability improvement with an active, explicitly scoped requirement.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR explicitly reports that no current-head native Windows setup run was captured; CI and source-contract tests are supplemental, not proof of this WinUI flow. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P2: This is a bounded first-run and channel-setup usability improvement with an active, explicitly scoped requirement.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR explicitly reports that no current-head native Windows setup run was captured; CI and source-contract tests are supplemental, not proof of this WinUI flow. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Active canonical requirement: The related open issue explicitly requires separating Gateway connection from channel readiness and providing an exact terminal handoff with expected result and return-to-app verification.
• Proposed implementation: The supplied PR diff adds a typed Channels completion destination, routes the restarted tray into Channels, and expands the gateway-host plugin guidance. (src/OpenClaw.SetupEngine.UI/SetupWindow.xaml.cs, 6a3cb68de4d8)
• Missing real behavior proof: The PR body states “Not verified / blocked” and provides no current-head native Windows run showing completion, Channels navigation, and channel refresh after plugin installation.
• Automated checks: The provided GitHub context reports successful build, test, setup-connect E2E, and CodeQL checks, but these do not demonstrate the changed WinUI flow in a real setup.
• Inspection infrastructure blocker: Read-only local inspection could not start because the sandbox failed before command execution with “bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted”; source history, full branch diff, and maintainer notes could not be independently inspected.
• Applicable repository policy: The supplied full repository AGENTS.md requires native Windows UI proof and the build plus Shared and Tray test closeout for setup and tray changes. (AGENTS.md, bc518f7bd158)

Likely related people:

• RomneyDa: Authored the open, member-associated issue whose definition of done this PR implements. (role: related requirement author; confidence: low)
• samanthamsong: Authored the broader open first-run onboarding epic referenced by this PR. (role: adjacent product owner; confidence: low)

Rank-up moves

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

• Capture a redacted current-head Windows run showing setup completion, Channels navigation, and Refresh after the gateway-host plugin step.
• From a native Windows host, report the required build, Shared-test, and Tray-test results in the PR body.

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.

[clawsweeper]

ClawSweeper feedback follow-up (current head 6a3cb68de4d86b942db50c548dc4d96adbfcc8d2):

• Exact-head Windows CI is green, including test, both architecture builds, and all three E2E shards.
• I retried native UI proof on 2026-08-15 using Crabbox AWS Windows desktop lease cbx_129687b80dc6 (violet-crab). Source sync succeeded, but the stock image lacks .NET 10, Node LTS, Windows SDK 26100, WebView2, and App Installer / winget; scripts/setup-dev.ps1 could not repair it.
• Azure provisioning failed before lease creation because the available low-priority core quota is 3 and the Windows class requires 16.

The requested visible setup-completion to Channels walkthrough remains not verified. This PR stays draft; green automation is recorded but is not being presented as UI proof.