Summary

Fixes the pairing required regression from #21236 for legacy paired devices that were created without roles / scopes metadata.

This PR includes two separate commits:

1. Repro regression test (server.auth.e2e.test.ts) that models legacy paired metadata.
2. Handshake fix in message-handler.ts to tolerate legacy metadata and backfill it in place.

Related maintainer draft: #21347 (used as reference/inspiration).

Problem

After handshake hardening, a previously paired device could be treated as a scope/role upgrade if its persisted paired record lacked roles/scopes, causing:

• gateway closed (1008): pairing required
• failed CLI/gateway commands after upgrade

What changed

1) Repro test

• Added allows legacy paired devices missing role/scope metadata in src/gateway/server.auth.e2e.test.ts.
• Test flow:
  1. Pair device normally.
  2. Remove roles and scopes from persisted paired record.
  3. Reconnect with same device and scope.
  4. Assert connect succeeds and metadata is backfilled.

2) Handshake fix

• In src/gateway/server/ws-connection/message-handler.ts:
  • detect legacy paired metadata shape (roles === undefined && scopes === undefined)
  • skip upgrade-pairing enforcement only for that legacy shape
  • still call updatePairedDeviceMetadata(...) so metadata is repaired in-place

Why this is safe

• Existing strict upgrade checks remain unchanged for non-legacy paired records.
• Existing paired entry is preserved; metadata is merged/backfilled in-place.
• Existing token entries are not dropped by this change.

Verification evidence

Repro was red pre-fix

Command:

pnpm exec vitest run --config vitest.e2e.config.ts src/gateway/server.auth.e2e.test.ts --testNamePattern "allows legacy paired devices missing role/scope metadata" --maxWorkers=1

Observed pre-fix failure:

• AssertionError: expected false to be true
• at src/gateway/server.auth.e2e.test.ts (expect(reconnect.ok).toBe(true))

Post-fix targeted checks

Command:

pnpm exec vitest run --config vitest.e2e.config.ts src/gateway/server.auth.e2e.test.ts --testNamePattern "allows legacy paired devices missing role/scope metadata|requires pairing for scope upgrades" --maxWorkers=1

Result:

• 1 passed, 2 passed | 29 skipped

Post-fix auth file checks

Command:

pnpm exec vitest run --config vitest.e2e.config.ts src/gateway/server.auth.e2e.test.ts --maxWorkers=1

Result:

• 1 passed, 31 passed

Manual single-host install validation

Using a normal local install pattern with an isolated state dir:

1. Start gateway locally, pair once (openclaw health passes).
2. Remove roles/scopes from devices/paired.json for the paired device.
3. Before fix: openclaw health returns gateway closed (1008): pairing required.
4. After fix: openclaw health succeeds, and devices/paired.json shows roles/scopes backfilled.

User-facing guidance (for #21236)

• Users should update to a release containing this fix, restart gateway, and run openclaw health.
• Existing pairings should continue working; legacy metadata is repaired automatically on reconnect.
• Users who already applied workaround steps that moved/deleted pairing files may still need re-approval/reconnect (expected when pairing state was reset).

Fixes #21236

Greptile Summary

Fixes regression where legacy paired devices without roles/scopes metadata were incorrectly rejected as upgrade attempts. The fix detects the legacy metadata shape (roles === undefined && scopes === undefined) and skips upgrade enforcement while still backfilling metadata via updatePairedDeviceMetadata(). Includes comprehensive test that validates the backfill behavior.

Confidence Score: 5/5

• Safe to merge with minimal risk
• The fix is narrowly scoped to detect and handle legacy metadata (both roles and scopes undefined) while preserving all existing upgrade checks for non-legacy paired devices. The test comprehensively validates the backfill behavior, and the updatePairedDeviceMetadata function properly merges metadata to repair legacy entries.
• No files require special attention

_{Last reviewed commit: fda21f1}