[pamelachia]

Plan-gated Management API denials already return { error: { code: "entitlement_required", feature, upgrade_url } }. In --output-format json and stream-json that signal only survives as escaped text inside error.message, so an agent has to parse prose to learn that an upgrade is needed and where. I added a structured entitlement to the machine-mode error object for every command whose status errors go through mapHttpError.

{"_tag":"Error","error":{"code":"DomainsUnexpectedStatusError","message":"...","entitlement":{"feature":"custom_domain","upgrade_url":"https://supabase.com/dashboard/org/<slug>/billing"}}}

Changed:

• Machine-mode errors carry the plan gate: on a 4xx, mapHttpError decodes the untruncated body and, when it is the plan-gate envelope, attaches entitlement: { feature, upgrade_url } to the status error. normalizeCliError passes it into the json and stream-json error object, so commands with no per-command upgrade wiring (branches unpause) get it too.
• Handlers that rebuild a mapped error keep it: branches create/update, vanity-subdomains activate/check-availability and sso list/add/update/remove forward the field, and Output.fail declares it in its type.
• Envelope values are validated in one place: I moved the parser into http-errors.ts and suggestUpgrade reuses it. feature must be a plain key and upgrade_url an http(s) URL without credentials, emitted as the parsed URL so control and bidi characters arrive percent-encoded; anything else counts as no envelope.

Note: text output and cli_upgrade_suggested are unchanged for well-formed envelopes. The per-command text hint stays until I move the hint and the event onto the same central path in a follow-up.

Linear

• part of GROWTH-1050

[pamelachia]

Manual check from source against the Management API on a free-plan org:

• supabase domains get --project-ref <ref> --output-format json, expect entitlement: { feature: "custom_domain", upgrade_url: ".../org/<slug>/billing" } on the error object
• same with --output-format stream-json, expect entitlement on the type: "error" event
• SUPABASE_EXPERIMENTAL=1 supabase vanity-subdomains get --project-ref <ref> --output-format json, expect entitlement.feature: "vanity_subdomain"
• supabase domains get --project-ref <ref> --agent no, expect the text-mode "Upgrade your plan: .../billing" hint
• stub API returning the envelope with upgrade_url: "javascript:alert(1)", expect no entitlement; a plain 403, expect no entitlement

[Coly010]

LGTM, a couple of small non-blocking asks inline