Skip to content

[Repo Assist] fix(setup): surface actionable error when gateway device-pair plugin is not loaded#747

Draft
github-actions[bot] wants to merge 1 commit into
mainfrom
repo-assist/eng-device-pair-plugin-not-found-2026-06-11-8f330ecd7f643284
Draft

[Repo Assist] fix(setup): surface actionable error when gateway device-pair plugin is not loaded#747
github-actions[bot] wants to merge 1 commit into
mainfrom
repo-assist/eng-device-pair-plugin-not-found-2026-06-11-8f330ecd7f643284

Conversation

@github-actions

Copy link
Copy Markdown
Contributor

🤖 This is an automated pull request from Repo Assist.

Relates to #677.

Problem

When a user's gateway CLI is older than 2026.6.0, the device-pair plugin is not loaded, and openclaw nodes list --json / openclaw nodes approve exit non-zero with:

plugins.entries.device-pair: plugin not found: device-pair

Previously AutoApproveNodePairing and AutoApprovePairing returned StepResult.Fail with the raw CLI output and then retried three times before ultimately surfacing a vague failure message:

"Could not list pending node pairing requests (exit 1): ..."

The user had no clear indication that the root cause was their gateway version.

Fix

  • Added ApprovalRequestHelper.IsPluginNotFoundError(string output) — a lightweight string check for the "plugin not found" substring (case-insensitive).
  • Added ApprovalRequestHelper.PluginNotFoundMessage — a shared, actionable message text directing users to upgrade to 2026.6.0+.
  • Applied detection at three failure points:
    • AutoApproveNodePairing → listing pending requests fails
    • AutoApproveNodePairing → approval command fails
    • AutoApprovePairing → approval command fails
  • Returns StepResult.Terminal (non-retriable) so the setup engine stops immediately with a clear message instead of retrying.

Trade-offs

The detection is a simple substring match. If a future gateway release changes the error wording, it will fall through to the existing Fail path (no regression, just loses the improvement). No new dependencies.

Test Status

Passed! — Failed: 0, Passed: 253 (out of 254), Skipped: 0

The 1 failure (Constructor_SetsLocalDataDirFromLocalAppDataRootEnvironment) is pre-existing on main and unrelated to this change (confirmed by running the same test against main with identical infrastructure). All ApprovalRequestHelper tests, including the 7 new IsPluginNotFoundError tests, pass.

Generated by 🌈 Repo Assist, see workflow run. Learn more.

Add this agentic workflows to your repo

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@97143ac59cb3a13ef2a77581f929f06719c7402a

…is not loaded

When the gateway CLI lacks the device-pair plugin (versions prior to
2026.6.0), 'openclaw nodes list --json' and 'openclaw nodes approve'
exit non-zero with output containing 'plugin not found: device-pair'.

Previously, AutoApproveNodePairing and AutoApprovePairing returned
StepResult.Fail with the raw CLI output and then retried 3 times before
reporting a vague failure. After retries the error surfaced as:
  'Could not list pending node pairing requests (exit 1): ...'

This change:
- Adds ApprovalRequestHelper.IsPluginNotFoundError to detect this pattern
- Returns StepResult.Terminal (non-retriable) with an actionable message
  pointing the user to upgrade their gateway to 2026.6.0+
- Covers both the 'list pending' and 'approve' command paths in
  AutoApproveNodePairing, and the 'approve' command path in AutoApprovePairing
- Adds tests for IsPluginNotFoundError in ApprovalRequestHelperTests

Relates to #677.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@clawsweeper

clawsweeper Bot commented Jun 11, 2026

Copy link
Copy Markdown

Codex review: needs changes before merge. Reviewed June 11, 2026, 10:08 AM ET / 14:08 UTC.

Summary
The PR detects missing-plugin text at three pairing command failure sites and returns a non-retriable message directing users to upgrade their gateway.

Reproducibility: yes. at source level: the current pairing paths return retriable failures for the reported non-zero CLI result, and the linked report supplies the exact diagnostic and affected gateway version. The PR does not include a live after-fix run.

Review metrics: 3 noteworthy metrics.

  • Error paths changed: 3 pairing failure paths. Every changed site becomes non-retriable when the shared classifier matches.
  • Test coverage added: 7 matcher cases, 0 step-level cases. The tests cover substring behavior but not terminal results or preservation of unrelated failure handling.
  • Patch surface: 3 files, 44 additions, 3 deletions. The repair remains focused enough for a narrow follow-up revision.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🦐 gold shrimp
Result: blocked until real behavior proof from a real setup is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Restrict matching to the explicit device-pair diagnostic.
  • [P1] Add step-level tests covering terminal and unrelated-plugin results.
  • [P1] Post redacted after-fix output from an affected gateway.

Proof guidance:

  • [P1] Needs real behavior proof before merge: The PR reports unit tests but no after-fix evidence from a real affected gateway; add redacted terminal output, setup logs, or a recording, then update the PR body to trigger review or ask a maintainer to comment @clawsweeper re-review.

Risk before merge

  • [P1] An unrelated missing plugin encountered while loading gateway configuration would be reported as a missing device-pair plugin and converted into a non-retriable setup failure.
  • [P1] The PR has no after-fix evidence from an affected gateway proving that setup stops immediately and displays the intended recovery guidance.

Maintainer options:

  1. Narrow the classifier before merge (recommended)
    Require both the missing-plugin diagnostic and the device-pair identifier, then test that unrelated missing plugins retain the existing retriable failure path.
  2. Pause for gateway contract confirmation
    Pause the PR if maintainers cannot confirm the minimum supported gateway version or stable diagnostic shape used for this recovery guidance.
Copy recommended automerge instruction
@clawsweeper automerge

Special instructions:
Narrow missing-plugin detection to the explicit device-pair diagnostic, preserve existing handling for unrelated missing plugins, and add focused SetupEngine tests for terminal versus retriable results.

Next step before merge

  • [P2] The classifier defect is a narrow mechanical repair suitable for the PR branch, while contributor-supplied real behavior proof remains a separate merge requirement.

Security
Cleared: The focused C# and test changes add no dependency, permission, secret, downloaded artifact, or supply-chain surface.

Review findings

  • [P2] Restrict the terminal error to the device-pair plugin — src/OpenClaw.SetupEngine/ApprovalRequestHelper.cs:27-28
Review details

Best possible solution:

Match the explicit device-pair plugin-not-found diagnostic, preserve ordinary failure handling for other plugins, add step-level regression coverage, and verify the final message against a real affected gateway.

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

Yes at source level: the current pairing paths return retriable failures for the reported non-zero CLI result, and the linked report supplies the exact diagnostic and affected gateway version. The PR does not include a live after-fix run.

Is this the best way to solve the issue?

No, not in its current generalized form; terminal handling is suitable for the known compatibility error, but the classifier must specifically identify device-pair so unrelated failures are not misdiagnosed.

Full review comments:

  • [P2] Restrict the terminal error to the device-pair plugin — src/OpenClaw.SetupEngine/ApprovalRequestHelper.cs:27-28
    This predicate accepts any output containing plugin not found, but all callers report a missing device-pair plugin and stop retries. If another configured plugin is missing, setup will now terminate with incorrect upgrade guidance; require the output to identify device-pair before returning this terminal result.
    Confidence: 0.94

Overall correctness: patch is incorrect
Overall confidence: 0.94

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

  • add P2: This is a normal-priority correction for a bounded but user-blocking setup pairing failure.
  • add merge-risk: 🚨 compatibility: The broad terminal classifier can stop existing setup workflows for unrelated missing-plugin configurations with misleading recovery instructions.
  • add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦐 gold shrimp.
  • 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 reports unit tests but no after-fix evidence from a real affected gateway; add redacted terminal output, setup logs, or a recording, then update the PR body to trigger review or ask a maintainer to comment @clawsweeper re-review.

Label justifications:

  • P2: This is a normal-priority correction for a bounded but user-blocking setup pairing failure.
  • merge-risk: 🚨 compatibility: The broad terminal classifier can stop existing setup workflows for unrelated missing-plugin configurations with misleading recovery instructions.
  • rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦐 gold shrimp.
  • status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR reports unit tests but no after-fix evidence from a real affected gateway; add redacted terminal output, setup logs, or a recording, then update the PR body to trigger review or ask a maintainer to comment @clawsweeper re-review.
Evidence reviewed

Acceptance criteria:

  • [P1] ./build.ps1.
  • [P1] dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore.
  • [P1] dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore.
  • [P1] dotnet test ./tests/OpenClaw.SetupEngine.Tests/OpenClaw.SetupEngine.Tests.csproj.

What I checked:

  • Overbroad classification: The new predicate accepts any output containing “plugin not found,” while every caller reports that the device-pair plugin is missing and makes the failure terminal. (src/OpenClaw.SetupEngine/ApprovalRequestHelper.cs:27, 6013bf5da26a)
  • Terminal impact: The shared classifier controls three changed pairing failure paths, replacing the existing retriable result with an immediate terminal result. (src/OpenClaw.SetupEngine/SetupSteps.cs:1899, 6013bf5da26a)
  • Pairing provenance: Blame ties the current approval helper and pairing command paths to the onboarding/setup implementation introduced by commit 85445c7. (src/OpenClaw.SetupEngine/SetupSteps.cs:1852, 85445c78066b)
  • Related user report: The linked issue reports the exact device-pair diagnostic after setup installed gateway CLI version 2026.5.28, supporting the need for actionable compatibility guidance.
  • Proof assessment: The PR body reports unit-test results but contains no terminal output, setup logs, recording, or linked artifact showing the changed behavior on an affected gateway. (6013bf5da26a)

Likely related people:

  • Christine Yan: Commit 85445c7 introduced the current approval helper and the pairing paths modified by this PR. (role: feature introducer; confidence: high; commits: 85445c78066b; files: src/OpenClaw.SetupEngine/ApprovalRequestHelper.cs, src/OpenClaw.SetupEngine/SetupSteps.cs)
  • Ranjesh: Commit cefce39 introduced the out-of-process SetupEngine architecture containing the affected step and command-runner boundaries. (role: setup-engine architect; confidence: medium; commits: cefce3952ab1; files: src/OpenClaw.SetupEngine/SetupSteps.cs, src/OpenClaw.SetupEngine/CommandRunner.cs)
  • Régis Brid: Recent commits modified the central setup-step file and adjacent runtime/error-handling behavior. (role: recent area contributor; confidence: medium; commits: 753828f63e96, 5505a85da7df; files: src/OpenClaw.SetupEngine/SetupSteps.cs)
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.

@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P2 Normal priority bug or improvement with limited blast radius. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. labels Jun 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

automation merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. P2 Normal priority bug or improvement with limited blast radius. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. repo-assist status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants