[egaodd]

WHY are these changes introduced?
Found in the service accounts bug bash (P2): a dev-stores-only service account token running shopify app versions list was told "The custom token provided can't be used for the App Management API. Ensure the token is correct and not expired." The token was valid; it just has no app access. A revoked token got exactly the same message, so you couldn't tell which problem you had.

WHAT is this pull request doing?
Identity already says which it is in the exchange response's error_description: Invalid 'scope' value: new scopes must not be specified (or no useable scope) when the token doesn't hold a scope the exchange asked for, and Invalid 'subject_token' value: … when the token itself is refused (revoked, expired, malformed, unknown). The CLI logged that in --verbose output and then threw it away.

tokenRequest keeps the description and InvalidRequestError carries it.
The automation-token exchange picks its message from it:
missing scope: "The service account behind SHOPIFY_SERVICE_ACCOUNT_TOKEN doesn't have App development access", with the capability named the way the admin names it (App development / Dev store management) and where to grant it. A legacy SHOPIFY_APP_AUTOMATION_TOKEN / SHOPIFY_CLI_PARTNERS_TOKEN is pointed at a service account token instead.
refused token: "The token in was rejected: it has been revoked, has expired, or isn't a valid token."
anything else, including Identity's third 'scope' message (about the CLI's own request) and network failures, keeps today's wording.
Identity's own wording still only reaches the debug log.
How to test your changes?
Verified against production (org 299069):

A dev-stores-only service account token running shopify app versions list prints the "doesn't have App development access" banner; --verbose shows Identity's Invalid 'scope' value: new scopes must not be specified.
A made-up token running shopify store list prints the "was rejected: it has been revoked, has expired, or isn't a valid token" banner.
Unit tests in exchange.test.ts cover the scope description, the subject_token descriptions (400 and the 401 "inactive" variant), and the legacy-variable wording. tsc and eslint pass on cli-kit.

Measuring impact
n/a (bug fix)
Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• Changeset added (@shopify/cli-kit, @shopify/cli: patch)

[lizkenyon]

Non-blocking, AI-assisted review: Could we also tell users to unset the legacy variable when setting SHOPIFY_SERVICE_ACCOUNT_TOKEN? Otherwise, adding the new variable while leaving the old one set triggers the CLI's variable-conflict error and costs another failed attempt.

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/private/node/session/exchange.d.ts

@@ -4,6 +4,9 @@ import { Result } from '../../../public/node/result.js';
 export declare class InvalidGrantError extends Error {
 }
 export declare class InvalidRequestError extends Error {
+    /** Identity's `error_description`, when it sent one. Says what about the request was invalid. */
+    readonly description: string;
+    constructor(description?: string);
 }
 export interface ExchangeScopes {
     admin: string[];