Distinguish Arcade auth blockers from gateway failures (GRO-354)

[teallarson]

Linear ticket: GRO-354

What/why

Arcade authentication blockers and gateway failures need different outcomes. An explicit needsAuth signal—or a present Arcade namespace with zero tools—should ask the user to authenticate Arcade. A missing, unavailable, or failing gateway is a setup/connection failure and must not be mislabeled as authentication.

For external-service work, agents must not silently substitute another MCP server, CLI, or direct API. Arcade-local retry and troubleshooting are still allowed, and app-level sign-in remains separate from gateway authentication.

To smoke-test, disconnect or misconfigure the plugin gateway and confirm the agent reports a setup/connection failure instead of asking for auth. Then trigger an explicit needsAuth state and confirm the agent stops for authentication instead of falling back to another connector.

Codebase changes

• Aligns the shared routing guidance, try-arcade skill, Cursor rule, and arcade-operator outcome contract.
• Returns needs_auth only for explicit Arcade authentication states and failed with the actual setup/connection error for unavailable gateways.
• Keeps Cursor's per-turn routing in the always-apply rule; beforeSubmitPrompt remains telemetry-only in Plugin telemetry: routing funnel, discovery link, MCP headers (GRO-305) #11.
• Adds cross-surface tests that prevent auth and availability wording from being conflated.

Additional notes

This PR targets #9; #11 targets this PR. Merge order: #9, then #10, then #11. npm run verify passes locally and the GitHub check job is green on head.

---

Note

Low Risk
Changes are prompt, skill, and hook guidance plus tests—no runtime auth or gateway code—so risk is limited to agent behavior when Arcade is misconfigured or unauthenticated.

Overview
Aligns Arcade routing across the arcade-operator agent, Cursor rule, shared hook guidance, and try-arcade skill so agents treat gateway authentication (needsAuth or a present plugin namespace with zero tools) differently from setup/connection failures (missing, unavailable, or failing gateway).

needs_auth is reserved for explicit auth blockers (authenticate in host MCP settings); failed carries the real connection/setup error. Cursor’s plugin-arcade-arcade namespace is documented as equivalent to arcade when it points at api.arcade.dev.

When Arcade is blocked, agents must not silently finish via another MCP server, CLI, or direct API; Arcade-local retry/troubleshooting stays allowed, and app-level sign-in remains separate from gateway auth. Hook tests now assert the split wording and require the new markers in injected context.

^{Reviewed by Cursor Bugbot for commit ad43a97. Bugbot is set up for automated code reviews on this repo. Configure here.}

[teallarson]

cursor review

[cursor]

Stale Bugbot comment from a previous run.

[teallarson]

@BugBot review

[cursor]

Stale Bugbot comment from a previous run.

[teallarson]

@BugBot review

[cursor]

Stale Bugbot comment from a previous run.

[teallarson]

@BugBot review

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4ae2c95. Configure here.}