fix(handlers): canonical error envelope (request_id) on 3 agent-facing branches (#234)

Three agent-facing error branches emitted a bespoke envelope missing
request_id (and one used a non-standard "msg" key), so an agent couldn't
correlate the failure to logs/support the way every respondError path lets it:

- onboarding.go ClaimPreview invalid_token (not-found): routed through
  respondError — adds request_id, swaps the bespoke "msg" for the canonical
  "message" key. The `error` keyword (what clients match on) is unchanged.
- env_policy.go Put owner_required 403: added request_id alongside the
  existing role/allowed_roles/agent_action fields.
- resource.go respondPauseUpgradeRequired 402: added request_id alongside
  the existing upgrade_url/agent_action.

No contract break — only additive (request_id) plus the msg→message rename on
a branch whose documented shape was just {ok,error}. All three changed lines
covered by existing tests (claim-preview not-found, env-policy non-owner,
pause-tier-wall); verified locally against real Postgres+Redis.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mastermanas805

internal/handlers/env_policy.go

@@ -100,6 +100,7 @@ func (h *EnvPolicyHandler) Put(c *fiber.Ctx) error {
 			"role":          role,
 			"allowed_roles": []string{middleware.RoleOwner},
 			"agent_action":  newAgentActionOwnerRequired(role),
+			"request_id":    middleware.GetRequestID(c),
 		})
 	}
 

internal/handlers/onboarding.go

@@ -96,11 +96,10 @@ func (h *OnboardingHandler) ClaimPreview(c *fiber.Ctx) error {
 	if err != nil {
 		var notFound *models.ErrOnboardingNotFound
 		if errors.As(err, &notFound) {
-			return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{
-				"ok":    false,
-				"error": "invalid_token",
-				"msg":   "Token not recognized",
-			})
+			// Canonical envelope: respondError adds request_id and uses the
+			// standard "message" key (this branch previously emitted a bespoke
+			// "msg" field with no request_id — agents couldn't correlate it).
+			return respondError(c, fiber.StatusBadRequest, "invalid_token", "Token not recognized")
 		}
 		slog.Error("onboarding.claim_preview.db_error", "error", err, "request_id", requestID)
 		return respondError(c, fiber.StatusServiceUnavailable, "lookup_failed", "Failed to verify token")

internal/handlers/resource.go

@@ -813,6 +813,7 @@ func respondPauseUpgradeRequired(c *fiber.Ctx, currentTier string) error {
 		"message":      "Pausing resources requires the Pro plan or higher. Your team is on the " + currentTier + " plan.",
 		"upgrade_url":  "https://instanode.dev/pricing",
 		"agent_action": AgentActionPauseRequiresPro,
+		"request_id":   middleware.GetRequestID(c),
 	})
 	return ErrResponseWritten
 }