docs(gateway): document node pairing repair flow

CHANGELOG.md

@@ -32,6 +32,7 @@ Docs: https://docs.openclaw.ai
 - Subagents/tasks: keep subagent completion and cleanup from crashing when task-registry writes fail, so a corrupt or missing task row no longer takes down the gateway during lifecycle finalization. Thanks @vincentkoc.
 - Sandbox/browser: compare browser runtime inspection against `agents.defaults.sandbox.browser.image` so `openclaw sandbox list --browser` stops reporting healthy browser containers as image mismatches. (#58759) Thanks @sandpile.
 - Exec/approvals: resume the original agent session after an approved async exec finishes, so external completion followups continue the task instead of waiting for a new user turn. (#58860) Thanks @Nanako0129.
+- Gateway/node pairing: create repair pairing requests when a paired node reconnects with allowlisted commands missing from its approved node record, refresh stale pending repair metadata, and surface paired node command metadata in `nodes status`/`describe` even while the node is offline. Fixes #58824.
 
 ## 2026.3.31
 

docs/gateway/pairing.md

@@ -65,10 +65,19 @@ Notes:
 
 - `node.pair.request` is idempotent per node: repeated calls return the same
   pending request.
+- Repeated requests for the same pending node also refresh the stored node
+  metadata and allowlisted command set, so reconnect-driven repair flows do not
+  stay stuck on stale pending data.
 - Approval **always** generates a fresh token; no token is ever returned from
   `node.pair.request`.
 - Requests may include `silent: true` as a hint for auto-approval flows.
 
+If a node is already paired but reconnects while declaring allowlisted commands
+that are missing from its approved node record, the gateway creates a repair
+pairing request. The current connection stays fail-closed on the previously
+approved command set until that repair request is approved and the node
+reconnects again.
+
 ## Auto-approval (macOS app)
 
 The macOS app can optionally attempt a **silent approval** when:

docs/nodes/troubleshooting.md

@@ -76,6 +76,11 @@ openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"
 If pairing is missing, approve the node device first.
 If pairing is fine but `system.run` fails, fix exec approvals/allowlist.
 
+If `nodes describe` shows the node connected but the expected command is missing,
+the approved node-pair record may be stale. In that case, reconnecting the node
+should create a repair pairing request; approve it, then reconnect once more so
+the gateway can expose the refreshed command set.
+
 ## Common node error codes
 
 - `NODE_BACKGROUND_UNAVAILABLE` → app is backgrounded; bring it foreground.