[diegosouzapw]

Root cause

studio-api.suno.ai (both open-sse/config/musicRegistry.ts and the duplicate
open-sse/config/providers/registry/suno/index.ts) returns 503 Service Suspended
(Cloudflare) for every request — the host is permanently down. The live client host,
studio-api-prod.suno.com, requires a Clerk JWT exchanged from a __client cookie via
auth.suno.com, device-id/browser-token headers, and an hCaptcha challenge solved
through a headless browser plus a paid captcha-solving service (per the community
reference implementation, gcui-art/suno-api) — none of which OmniRoute's current
cookie-only fetch flow implements.

Fix

Per owner decision (binding, recorded in the plan-file frontmatter): retire the
suno provider rather than rewrite its auth (the Clerk JWT + hCaptcha path is out of
scope — new paid external dependency for one provider).

• Removed the suno entry from musicRegistry.ts and the duplicate registry copy
  (open-sse/config/providers/registry/suno/), and its handleSunoMusicGeneration
  dispatch/branch in musicGeneration.ts.
• Dropped suno from the API-key catalog (specialty-media.ts) and its icon wiring
  (ProviderIcon.tsx, lobeProviderIcons.ts).
• Registered the takedown in docs/reference/REMOVED_PROVIDERS.md and guarded it via
  tests/unit/removed-providers-blocklist.test.ts (new music-registry-entry assertion +
  source-sweep, matching the puter/theoldllm precedent).
• kie/suno-v4.0 and kie/suno-v3.5 (kie.ai-hosted, unrelated cookie flow) are
  unaffected and remain supported — API_REFERENCE.md's example now points at one of
  them instead of the retired native provider.
• Regenerated PROVIDER_REFERENCE.md (359 → 358 providers) and corrected the
  provider-count literal everywhere check:docs-all asserts it against live code:
  package.json description and the README hero/promise-pillars/comparison-table/
  cli-terminal/tier-flow SVGs.
• Dropped the now-orphaned onboardingProviderDescriptions.suno i18n key from all 66
  locale catalogs (same treatment as the puter/theoldllm removals).

Regression test

tests/unit/removed-providers-blocklist.test.ts — added suno to REMOVED_PROVIDERS
plus a new MUSIC_PROVIDERS[removed.id] assertion (the plan-file's repro, folded into
the blocklist contract instead of a standalone throwaway file).

RED (pre-fix, proven by reverting the implementation diff with git apply -R and
re-running against the unmodified test — not by switching branches):

✖ removed provider "suno" identifiers and domains are absent from registry/executor sources
  AssertionError: reintroduction of "suno" detected — see docs/reference/REMOVED_PROVIDERS.md
  + [
  +   'open-sse/config/musicRegistry.ts :: "suno"',
  +   'open-sse/config/musicRegistry.ts :: studio-api.suno.ai',
  +   'open-sse/config/providers/registry/suno/index.ts :: "suno"',
  +   'open-sse/config/providers/registry/suno/index.ts :: studio-api.suno.ai',
  +   'src/shared/constants/providers/apikey/specialty-media.ts :: "suno"',
  + ]
  - []

GREEN (post-fix): tests 19 / pass 19 / fail 0 (all three REMOVED_PROVIDERS entries ×
6 assertions + the doc-sync check).

Gates run

• node --import tsx/esm --test tests/unit/removed-providers-blocklist.test.ts — 19/19 pass
• npm run typecheck:core — exit 0, 0 errors
• node scripts/check/check-open-sse-typecheck.mjs — openSseTypecheckErrors=0
• npx eslint --suppressions-location config/quality/eslint-suppressions.json <every changed source/test file> — 0 errors (3 pre-existing "file ignored" warnings on the docs/ markdown paths, expected)
• node scripts/check/check-file-size.mjs — OK, no files over baseline
• node scripts/check/check-complexity-ratchets.mjs --base-ref origin/release/v3.8.51 — OK, 0 changed files in the gate's source scope
• npm run check:provider-consistency — OK, 358 canonical providers, 0 registry-only exceptions
• npm run check:docs-all — 2 STRICT drifts remain (see Remaining below); all others resolved
• node scripts/check/check-changelog-integrity.mjs — pre-existing failure, see Remaining below

Existing tests

Ran every test file referencing "suno":

• tests/unit/minimax-media-servicekinds.test.ts, tests/unit/new-content-providers.test.ts, tests/unit/provider-service-kind-filter-4240.test.ts — aligned to the new contract (suno removed from the expected-cases/entries lists; two assertions flipped to explicitly prove suno is retired rather than registered). 48/48 pass across the four touched suites.
• tests/unit/registry-utils.test.ts, tests/unit/specialty-model-catalog-routes.test.ts, tests/unit/model-test-modality-guard-13376.test.ts, tests/unit/music-generation-handler.test.ts, tests/unit/provider-assets-third-party-notices.test.ts — reference "suno" only as a kie/suno-v4.0 model id, a synthetic test-only model string, a KIE response field name (sunoData), or a static third-party-notices/icon-scope list independent of the provider registry — none depend on the retired provider; left unchanged, ran green.
  • One unrelated pre-existing failure in tests/unit/specialty-model-catalog-routes.test.ts ("image catalog GET uses the unified active-credential model list", 503 instead of 200) — reproduces standalone on this file alone; the file and the route it exercises (src/app/api/v1/images/generations/route.ts) have zero diff against origin/release/v3.8.51, so this is a pre-existing environment/base issue, not caused by this change.

Remaining (accepted, not fixed here)

• check:docs-all: AGENTS.md and llm.txt still say "359 providers" — both are agent-instruction surfaces this session must not edit (repo convention: provider counts there are only refreshed centrally during the merge-train, per prior sessions' practice). Everything else check:docs-all flagged (package.json, the 6 README/hero SVGs, PROVIDER_REFERENCE.md) was fixed to 358.
• node scripts/check/check-changelog-integrity.mjs: fails with 474 missing bullets — ⚠️ base-red inherited. This branch was cut from origin/release/v3.8.51 at 06f1df9d; CHANGELOG.md at that point predates several since-landed reconciliation commits on the base (base has since advanced to 282db2a3). This diff never touches CHANGELOG.md; the changelog fragment for this fix lives at changelog.d/fixes/14224-retire-suno.md per convention.

Closes #14224

Plan-file: _tasks/pipeline/bugs/2-implementing/14224-fix-providers-suno-studio-api-suno-ai-returns-503-service-susp.plan.md

Rework (merge-batch 2026-09-23)

• Merged release/v3.8.51 (tip) into the branch (real merge, no rebase/force-push). Conflicts were only in generated counts: docs/diagrams/*.svg, public/images/tier-flow-*.svg, package.json description, docs/reference/PROVIDER_REFERENCE.md.
• Resolution: took the tip's version of those files, regenerated PROVIDER_REFERENCE.md with npm run gen:provider-reference (measured total: 359 after removing suno from a tip at 360), then aligned the provider count to 359 in the SVGs, package.json, README.md, AGENTS.md and llm.txt (+66 docs/i18n/*/llm.txt mirrors regenerated by scripts/i18n/sync-llm-mirrors.mjs). AGENTS.md/llm.txt changes are the provider count only.
• Validation: check:docs-counts 0 STRICT drift; check:docs-sync PASS (66 llm mirrors); check:provider-consistency OK (359 canonical); focused tests (removed-providers-blocklist, minimax-media-servicekinds, new-content-providers, provider-service-kind-filter-4240) 48/48 pass; typecheck:core only the inherited cliproxyAccountHealth.ts(157,5); eslint clean on changed files; file-size OK.
• Inherited (not from this PR): check:open-sse-typecheck flags open-sse/executors/auggie.ts TS2769/TS18047 — file identical to the tip (from fix(auggie): resolve spawn EINVAL when running the CLI shim on Windowsfix(auggie): resolve spawn EINVAL when running the CLI shim on Windows #14215).