pairing.md documents that commands are dropped during the pending st…

[Angfr95]

Problem: pairing.md documents that commands are dropped during the pending state but provides no operator guidance for recovery.
Solution: add a Troubleshooting section covering commands dropped before pairing approval, pending requests not appearing, and stale tokens after re-pair.
Evidence: Node command gating section documents the drop behavior but leaves operators without a recovery path.

Summary

• Problem: pairing.md has no troubleshooting guidance for the node command gating behavior introduced in 2026.3.31
• Why it matters: operators hitting dropped commands, missing pending entries, or stale tokens have no documented recovery path
• What changed: added a Troubleshooting section to docs/gateway/pairing.md with three scenarios
• What did NOT change (scope boundary): no code, no behavior, no other doc files

Change Type

• Docs

Scope

• Gateway / orchestration

Linked Issue/PR

N/A

Root Cause

N/A

Regression Test Plan

N/A

User-visible / Behavior Changes

None

Diagram

N/A

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Windows 11
• Runtime/container: N/A
• Model/provider: N/A
• Integration/channel: N/A
• Relevant config: N/A

Steps

1. Open docs/gateway/pairing.md on main
2. Search for troubleshooting guidance on dropped commands
3. Confirm no such section exists

Expected

• A troubleshooting section covering common operator issues after node command gating

Actual

• No troubleshooting content exists in the current file

Evidence

• Gap visible directly in docs/gateway/pairing.md — Node command gating section documents the drop behavior but provides no recovery path

Human Verification

• Verified scenarios: confirmed the three troubleshooting scenarios are consistent with existing doc content and do not contradict the WS device pairing / node.pair.* boundary
• Edge cases checked: wording stays within the node.pair.* store scope and does not bleed into device pairing
• What you did not verify: live CLI behavior

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

None

[clawsweeper]

Codex review: needs changes before merge. Reviewed May 31, 2026, 12:59 AM ET / 04:59 UTC.

Summary
The PR adds a Troubleshooting section to docs/gateway/pairing.md for dropped pending-state node commands, missing pending requests, and stale node-pairing tokens, plus punctuation normalization.

PR surface: Docs +22. Total +22 across 1 file.

Reproducibility: yes. for the documentation gap: current main documents dropped pending-state node commands but has no troubleshooting section. No runtime reproduction is needed for this docs-only PR.

Review metrics: none identified.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🌊 off-meta tidepool
Patch quality: 🦐 gold shrimp
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:

• Correct the stale-token recovery paragraph to use the current or freshly created pending request.
• Refresh the branch against current main and rerun docs validation.

Risk before merge

• [P1] The branch is currently dirty against main and the same docs page has changed since the PR base, so the final wording needs a refresh against current main before merge.

Maintainer options:

1. Decide the mitigation before merge
   Keep the troubleshooting addition, but correct stale-token recovery to approve the current or freshly created pending request and refresh the branch against current main before merge.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] A narrow automated docs repair can fix the stale-token paragraph and refresh the PR without runtime, product, or security decisions.

Security
Cleared: Docs-only changes do not modify code execution, credentials, workflows, dependencies, or supply-chain surfaces.

Review findings

• [P2] Describe approving a current pending request for token recovery — docs/gateway/pairing.md:222

Review details

Best possible solution:

Keep the troubleshooting addition, but correct stale-token recovery to approve the current or freshly created pending request and refresh the branch against current main before merge.

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

Yes for the documentation gap: current main documents dropped pending-state node commands but has no troubleshooting section. No runtime reproduction is needed for this docs-only PR.

Is this the best way to solve the issue?

No, not as written. Adding troubleshooting to this page is the right docs surface, but the stale-token paragraph should match approve/reject semantics and the branch needs refresh against current main.

Full review comments:

• [P2] Describe approving a current pending request for token recovery — docs/gateway/pairing.md:222
  The new stale-token guidance says to reject and re-approve the request, but rejectNodePairing removes the pending request while approveNodePairing only mints a new token from an existing pending request. Operators following this text can delete the only approvable request; tell them to approve the current pending request, or reconnect/re-run the node to create a fresh request before approving.
  Confidence: 0.88

Overall correctness: patch is incorrect
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P3: This is a docs-only gateway pairing improvement with no runtime change and a narrow correction path.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence reviewed

PR surface:

Docs +22. Total +22 across 1 file.

View PR surface stats

Area	Files	Added	Removed	Net
Source	0	0	0	0
Tests	0	0	0	0
Docs	1	25	3	+22
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	1	25	3	+22

Acceptance criteria:

• [P1] git diff --check.
• [P1] pnpm docs:list.
• [P1] pnpm docs:check-mdx.
• [P1] pnpm docs:check-links:anchors.

What I checked:

• Repository policy read: Root AGENTS.md and docs-scoped docs/AGENTS.md were read fully; the docs guide requires source-backed docs claims and Mintlify-safe internal links/headings. (AGENTS.md:1, e1a98171417c)
• Current main still has the docs gap: Current main documents that commands queued before node-pairing approval are dropped, but the page goes from transport behavior directly to Related links with no troubleshooting section. Public docs: docs/gateway/pairing.md. (docs/gateway/pairing.md:90, e1a98171417c)
• PR stale-token wording: The PR tells operators to reject and re-approve the request to issue a fresh token. Public docs: docs/gateway/pairing.md. (docs/gateway/pairing.md:221, 3fc2b7f57584)
• Approve contract: approveNodePairing only mints a fresh token from an existing pending request, then deletes that pending request and stores the paired node. (src/infra/node-pairing.ts:280, e1a98171417c)
• Reject contract: rejectNodePairing deletes the pending request through rejectPendingPairingRequest, so the docs should not describe rejecting and then re-approving the same request. (src/infra/node-pairing.ts:330, e1a98171417c)
• Command gating source: On an unpaired node, reconnect reconciliation creates or refreshes pending pairing and exposes no effective commands until approval. (src/gateway/node-connect-reconcile.ts:128, e1a98171417c)

Likely related people:

• Peter Steinberger: Local blame for the gateway pairing docs, node pairing implementation, and node connect reconciliation all resolves to the recent release commit that carries these current-main lines. (role: recent area contributor; confidence: medium; commits: 22e4289d3f05; files: docs/gateway/pairing.md, src/infra/node-pairing.ts, src/gateway/node-connect-reconcile.ts)

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.

[openclaw-barnacle]

This pull request has been automatically marked as stale due to inactivity.
Please add updates or it will be closed.