fix(onboarding): skip wizard for paired operators and make "Keep my setup" actually dismiss

[indierawk2k2]

Reported by @shanselman against latest master:

1. Tray app pops the onboarding wizard at launch even though there is already a working configuration with a connection to a remote gateway.
2. "Keep my setup" doesn't keep the setup — clicking it on the warn-and-confirm UI doesn't dismiss the wizard; the user can still advance into setup via the global Next button.

Root cause

1. StartupSetupState.RequiresSetup only short-circuited for node mode (EnableNodeMode + node device token) or MCP-only mode. An operator with a non-default gateway URL + stored device token still got the wizard popped at OnLaunched.
2. SetupWarningPage.CancelReplace only toggled in-page state. Worse, OnboardingWindow defaulted SetupPath = SetupPath.Advanced whenever existing config was detected, so the global nav-bar Next button stayed enabled and the user was one click from advancing into ConnectionPage.

Fix (commit b3b5b2f)

• New operator-mode short-circuit in StartupSetupState.RequiresSetup: returning users with both an operator device token and a configured gateway target skip the wizard.
• New OnboardingState.Dismiss() / Dismissed event. OnboardingWindow listens, sets a _dismissedWithoutCompletion guard, and Close()s — OnClosed skips TryCompleteOnboarding when guarded so OnboardingCompleted does NOT fire and existing settings/gateway connection are preserved.
• SetupWarningPage.CancelReplace calls Props.Dismiss().
• Belt-and-suspenders: dropped the auto-default of SetupPath = SetupPath.Advanced in OnboardingWindow. With SetupPath left null, the global Next button is disabled on SetupWarning, so the user MUST pick Replace my setup, Keep my setup, or Advanced setup explicitly.

Adversarial review fixes (commit 8338c5d)

Ran a Hanselman-style dual-model review (Claude Opus + GPT Codex) before sending. The two models surfaced complementary issues; all six actionable findings are folded in:

Finding	Source	Resolution
Per-gateway tokens missed (gateways/<id>/device-key-ed25519.json)	Codex HIGH	Scan added in HasAnyOperatorDeviceToken
SSH-tunnel users falsely re-prompted (loopback URL)	Codex HIGH	UseSshTunnel + SshTunnelHost counted as a configured target
MCP precedence regression (NodeMode=true + MCP=true + no node token)	Codex MEDIUM	MCP check moved before NodeMode
Close() exception left _dismissedWithoutCompletion=true permanently	Opus MEDIUM	Flag reset in catch block
DefaultGatewayUrl duplicated across two files	Opus HIGH	Promoted to OnboardingExistingConfigGuard.DefaultGatewayUrl (public const) + invariant test
CancelReplace UI flash from dead setConfirmingReplace(false)	Opus MEDIUM	Removed

Tests added

• StartupSetupStateTests: operator paired with remote returns false; operator+default URL still requires setup; non-default URL alone still requires setup; null/whitespace URL; SSH tunnel + token; SSH enabled but no host; per-gateway-only token; MCP+NodeMode+no node token bypass; DefaultGatewayUrl_MatchesGuardConstant invariant.
• OnboardingStateTests: Dismiss fires Dismissed; does NOT fire Finished; safe with no handler.

Validation

• ./build.ps1 ✅
• OpenClaw.Shared.Tests: 1548 passed, 28 skipped
• OpenClaw.Tray.Tests: 1180 passed (+5 new)

cc @shanselman — please give it a look when you can.

[shanselman]

Thanks for jumping on this. The overall direction looks right and CI is green, but I would hold this PR for one more fix before merge.

I ran a deeper review against the final two-commit diff. The main startup/dismiss flow looks sound: MCP precedence is preserved, per-gateway token scanning was added for startup, SSH tunnel mode is accounted for, and the Keep my setup dismiss path avoids firing the completion pipeline.

Blocking / should fix before merge

Existing-config guard still misses per-gateway operator tokens

StartupSetupState.HasAnyOperatorDeviceToken(...) now correctly scans both the legacy root identity and modern per-gateway identity directories under gateways/<gateway-id>/device-key-ed25519.json. However, OnboardingExistingConfigGuard.GetSummary() still only checks:

HasOperatorDeviceToken: DeviceIdentity.HasStoredDeviceToken(_identityDataPath)

That only sees the legacy root device-key-ed25519.json. Modern fresh pairings store the operator token in the per-gateway identity directory, so a user with only a per-gateway token can be treated as having no existing operator identity by the onboarding replacement guard.

Why this matters:

• Startup may now correctly skip onboarding for these users.
• But if they manually open Setup/Reconfigure, or reach local setup through another path, SetupWarningPage / LocalSetupProgressPage can fail to show/block on the existing-config warning.
• That means a modern paired user could accidentally overwrite a working gateway setup without the intended “Replace my setup / Keep my setup” protection.

Suggested fix:

• Reuse the same token detection semantics from StartupSetupState in OnboardingExistingConfigGuard, or extract a shared helper so both paths agree.
• Add a test that creates only gateways/<id>/device-key-ed25519.json and asserts OnboardingExistingConfigGuard.HasExistingConfiguration() is true and GetSummary().HasOperatorDeviceToken is true.

Example test shape:

[Fact]
public void HasExistingConfiguration_ReturnsTrue_WhenOperatorTokenStoredOnlyInPerGatewayDir()
{
    using var temp = TempSettings.Create();
    var perGatewayDir = Path.Combine(temp.Path, "gateways", "gw-abc");
    Directory.CreateDirectory(perGatewayDir);
    StoreDeviceToken(perGatewayDir);

    var settings = new SettingsManager(temp.Path);
    var guard = new OnboardingExistingConfigGuard(settings, temp.Path, setupStatePath: Path.Combine(temp.Path, "setup-state.json"));

    var summary = guard.GetSummary();
    Assert.True(summary.HasOperatorDeviceToken);
    Assert.True(summary.HasAny);
}

Lower-confidence / consider while touching this area

Startup token scan may treat orphan gateway identity dirs as usable

StartupSetupState.HasAnyOperatorDeviceToken(...) currently accepts any token under gateways/*. That fixes modern pairings, but it can also make an orphan identity directory count as usable even if it does not correspond to the active gateway record in gateways.json or the configured target.

The safer long-term model is probably:

1. Prefer the active GatewayRegistry record and check that record’s identity directory.
2. Fall back to legacy root identity only for migration/back-compat.
3. Avoid letting an arbitrary leftover gateways/<old-id> directory suppress onboarding for a different active/configured gateway.

I would not necessarily block this PR on the full registry-aware refactor if you want to keep it small, but it is worth either addressing now or tracking as a follow-up.

OnboardingState.Dismiss() could be idempotent

Dismiss() currently raises Dismissed every time it is called. The current window guards make the blast radius small, but since this is now a lifecycle signal, it would be more robust to make it idempotent:

private bool _dismissed;

public void Dismiss()
{
    if (_dismissed) return;
    _dismissed = true;
    Logger.Info("[OnboardingState] Dismiss invoked (user chose to keep existing setup)");
    Dismissed?.Invoke(this, EventArgs.Empty);
}

This is not a blocker, just a hardening suggestion.

Summary

Please fix the per-gateway identity detection in OnboardingExistingConfigGuard before merge. That is the one actionable gap both review passes agreed on. After that, this should be in good shape.

[indierawk2k2]

Thanks @shanselman — addressed in f65b742 (now pushed to PR).

Blocking fix

Extracted the per-gateway scan to OnboardingExistingConfigGuard.HasAnyOperatorDeviceToken as the single source of truth (was private to StartupSetupState). Both StartupSetupState.HasUsableOperatorConfiguration and OnboardingExistingConfigGuard.GetSummary().HasOperatorDeviceToken call it now, so the startup decision and the in-wizard guard agree on what counts as paired. Used your exact test shape — HasExistingConfiguration_ReturnsTrue_WhenOperatorTokenStoredOnlyInPerGatewayDir — and asserted both summary.HasOperatorDeviceToken and HasExistingConfiguration().

Hardening (also done)

Made OnboardingState.Dismiss() idempotent. Added Dismiss_IsIdempotent_FiresDismissedAtMostOnce test.

Deferred follow-up

The orphan-gateway-dir concern (registry-aware token resolution preferring the active record's identity dir over arbitrary gateways/* dirs) is real but a bigger refactor. Per your suggestion to keep this PR small, I'm tracking it as a follow-up rather than folding it in here. Happy to file an issue if you'd like a tracker.

Validation

• ./build.ps1 ✅
• OpenClaw.Shared.Tests: 1548 passed, 28 skipped
• OpenClaw.Tray.Tests: 1182 passed (+2 new vs previous push)

[shanselman]

I'm still clicking keep and it's still being ignored, and it's still sending me to the next page. The same dialog pops up when I run it again, every time. @indierawk2k2

[shanselman]

Follow-up from manual repro after merge: the Keep my setup dismissal path itself works, but startup setup detection still missed one local-node shape.

Sanitized repro state:

• EnableNodeMode=true
• root %APPDATA%\OpenClawTray\device-key-ed25519.json has no NodeDeviceToken
• per-gateway %APPDATA%\OpenClawTray\gateways\<gateway-id>\device-key-ed25519.json has NodeDeviceToken

Broken-run log excerpt:

[OnboardingState] Dismiss invoked (user chose to keep existing setup)
[OnboardingWindow] Dismissed by user (keep-existing-setup) — closing without completing
...
[OnboardingWindow] OnWizardComplete skipping chat launch; route=SetupWarning, setupStillRequired=True

Root cause: #340 added the per-gateway scan for operator tokens, but StartupSetupState.HasStoredNodeDeviceToken still checked only the legacy root identity file. In node mode that made RequiresSetup(...) stay true even though the node token existed under the active gateway identity directory.

I opened follow-up PR #375 with the fix and regression tests. After rebuilding x64, relaunch no longer opens onboarding; the post-launch log shows normal node auth instead:

Connecting to last successful gateway during startup: ws://localhost:18789 (identity.DeviceToken)
Connecting to node: ws://localhost:18789
[HANDSHAKE]   isBootstrap=False, hasNodeDeviceToken=True
Node registered successfully! ID: c340a12b10f1dacb