@enrichlayer/el-linear 1.44.2 → 1.46.0

package/README.md

@@ -111,6 +111,25 @@ el-linear init oauth --actor app
 App actor tokens can request `app:assignable` and `app:mentionable`, but not
 `admin`. The authorized app user ID is stored in `oauth.json` as `viewerId`.
 
+OAuth apps that have Linear's client-credentials grant enabled can obtain an
+app-user token without a browser. Keep the secret out of argv and source it
+through an environment variable:
+
+```bash
+export LINEAR_OAUTH_CLIENT_SECRET="..."
+el-linear init oauth --client-credentials --actor app \
+  --client-id your-linear-oauth-client-id
+```
+
+Use `--client-secret-env NAME` to read a differently named variable and
+`--scopes read,write,issues:create,comments:create` to override the configured
+scope set. The 0600 profile state stores the secret so el-linear can acquire a
+new token before expiry and once after an HTTP 401; client-credentials tokens
+do not have refresh tokens. Keep the scope set stable: Linear revokes an app's
+existing client-credentials tokens when a new token requests different scopes.
+This flow is opt-in. Remote automation can keep using `LINEAR_API_TOKEN`, which
+remains higher precedence than profile OAuth.
+
 At runtime, credentials are resolved in this order:
 
 1. `--api-token <token>` flag.
@@ -558,6 +577,83 @@ list-shaped reads — single-issue `issues read DEV-123` is unaffected.
 
 ## Output formats
 
+Commands whose request path exposes Linear response headers include aggregate
+quota observations as optional `_rateLimit` metadata in JSON output:
+
+```json
+{
+  "identifier": "DEV-123",
+  "_rateLimit": {
+    "limit": 2500,
+    "remaining": 2498,
+    "resetAt": "2026-08-11T10:00:00.000Z",
+    "observedRequests": 2,
+    "minimumRemaining": 2498,
+    "complexity": {
+      "cost": 30,
+      "totalCost": 50,
+      "limit": 2000000,
+      "remaining": 1999950,
+      "minimumRemaining": 1999950,
+      "resetAt": "2026-08-11T10:00:00.000Z"
+    },
+    "endpoints": {
+      "Issue": {
+        "limit": 1000,
+        "remaining": 998,
+        "minimumRemaining": 998,
+        "resetAt": "2026-08-11T10:00:00.000Z",
+        "observedRequests": 2
+      }
+    }
+  }
+}
+```
+
+Summary output renders the same information as an `_rateLimit:` line. With a
+bare-array output such as `--raw`, the line goes to stderr so stdout remains
+valid JSON. Current remaining/reset values come from the most recent response;
+`observedRequests`, `minimumRemaining`, `complexity.totalCost`, and each
+endpoint entry expose the command's aggregate cost and lowest observed
+headroom. Rate-limited error envelopes include the same metadata. Commands
+served entirely from cache omit it.
+
+Automation can reserve a request floor before issuing another GraphQL call:
+
+```bash
+export EL_LINEAR_RATE_LIMIT_HEADROOM=250
+export EL_LINEAR_QUOTA_KEY=verticalint-shared-linear-user
+```
+
+When Linear's last observed remaining count reaches the configured floor,
+`el-linear` refuses the request until the observed reset time instead of
+consuming capacity reserved for higher-priority work. Admission and response
+observations are serialized across local processes. The state filename is a
+SHA-256 digest; neither the credential nor `EL_LINEAR_QUOTA_KEY` is written in
+clear text. Set the same non-secret quota key for API keys belonging to the
+same Linear user, because Linear pools those keys by user. Without an explicit
+key, API keys coordinate by credential and OAuth tokens coordinate by token.
+Profile OAuth uses its stable app/viewer identity so token refreshes keep the
+same local quota state.
+
+This file-backed admission is intentionally a same-machine boundary. Separate
+hosts can opt into the companion distributed coordinator:
+
+```bash
+export EL_LINEAR_RATE_LIMIT_COORDINATOR_URL=https://el-linear-control-plane.example.workers.dev
+export EL_LINEAR_RATE_LIMIT_COORDINATOR_TOKEN="..."
+```
+
+The URL switches admission and observations to the coordinator's atomic
+Durable Object for the hashed quota key. Admission fails closed when that
+service is unavailable; a completed Linear response is never replayed merely
+because its observation could not be persisted. Without the URL, do not
+interpret the file-backed setting as distributed admission.
+
+Read-through cache misses for teams, projects, labels, and similar cached lists
+are also single-flighted across local processes, preventing a cold-cache burst
+from issuing the same request once per command.
+
 Every command accepts `--format <kind>` at the root:
 
 - `--format json` (default) — emits the full structured envelope. Stable
@@ -661,6 +757,69 @@ el-linear projects list --format summary --fields name,state,progress,lead,teams
 
 Unrecognized field names are reported as a `_warnings:` line appended after the summary block (`fields_unprojectable: --format summary on issues list does not project foo, bar; ...`) — same signal scripts get on the JSON path. Resources whose summary formatter doesn't yet wire `--fields` (cycles, milestones, project updates, comments, teams, labels, users, documents, templates, attachments, releases, search results) emit the same warning and render their default summary.
 
+### Error envelope
+
+Every command reports a failure the same way: **exit code 1**, and a
+single JSON object on **stdout** (the same stream as success, so a caller
+capturing one stream always gets exactly one parseable object).
+
+```json
+{
+  "error": "Ratelimit exceeded",
+  "activeProfile": "work",
+  "errorDetail": {
+    "httpStatus": 429,
+    "code": "RATELIMITED",
+    "retryable": true
+  }
+}
+```
+
+| Field           | Always present | Meaning                                                              |
+| --------------- | -------------- | -------------------------------------------------------------------- |
+| `error`         | yes            | The failure message, token-sanitized.                                |
+| `activeProfile` | yes            | Which profile the command ran under — distinguishes "not found" from "wrong workspace". |
+| `errorDetail`   | no             | Classification of a **Linear GraphQL** failure or quota admission refusal. See below. |
+
+`errorDetail` is emitted when the failure came from a request to the
+Linear GraphQL API or the quota admission that precedes it. Its fields:
+
+| Field        | Type             | Meaning                                                                 |
+| ------------ | ---------------- | ----------------------------------------------------------------------- |
+| `httpStatus` | `number \| null` | HTTP status of Linear's response; `null` when no response arrived.      |
+| `code`       | `string \| null` | The first GraphQL error's `extensions.code`; `null` when absent.        |
+| `retryable`  | `boolean`        | Whether the failure is transient — retrying after an appropriate wait could succeed. |
+| `resetAt`    | optional `string` | Known quota reset or recovery-probe deadline, normalized to a UTC ISO timestamp. |
+
+`retryable` is `true` for HTTP 408 / 429 / 5xx, for the `RATELIMITED`,
+`INTERNAL_SERVER_ERROR` and `SERVICE_UNAVAILABLE` GraphQL codes, and for a
+transport failure that never reached a response (`fetch failed`,
+`ECONNRESET`, …). Reading `code` separately matters: Linear can answer a
+rate limit under a status that would otherwise read as permanent, so
+`httpStatus` alone is not the whole verdict.
+
+`retryable: true` says the failure is transient — **not** that retrying
+immediately is a good idea. A rate limit is transient and reported as such,
+but its window may be minutes away; the wait is the caller's policy.
+
+A local or distributed quota admission refusal uses `code: "RATELIMITED"`,
+`retryable: true` and `httpStatus: null`: no request was sent to Linear.
+When known, `resetAt` comes from the quota state or the existing recovery-probe
+lease. Missing or malformed deadlines are omitted; message text never supplies
+a deadline. These refusals retain the configured headroom and do not trigger an
+immediate retry inside the CLI. The deadline permits a later attempt, not a
+guarantee of capacity or permission.
+
+**A missing `errorDetail` is not "not retryable".** It means the failure
+was not a classified Linear request or quota refusal — a bad argument, an unreadable
+`--file`, a missing token. Treat its absence as *unclassified* and apply
+your own policy; emitting a fabricated `retryable: false` there would let
+an argv typo masquerade as a verdict about Linear.
+
+Automation that shells out to `el-linear` (a job runner deciding whether
+to retry, say) should branch on `errorDetail.retryable` rather than
+substring-matching `error`.
+
 ### Windowed metadata (`WindowedMeta`)
 
 When a command returns less than its complete result set — because it

package/claude-skills/linear-operations/SKILL.md

@@ -468,6 +468,23 @@ The label is plain config — set it to anything you want, or skip it entirely.
 
 ---
 
+## Label advisor defaults and consent labels (`bot`)
+
+A workspace can configure a **label advisor** (`labelAdvisor.command` in personal config, or `EL_LINEAR_LABEL_ADVISOR`): a command `issues create` consults with the proposed issue. Whatever labels it returns are added and reported — a `labels added by advisor: … (<reason>)` warning on stderr and a `labelAdvisor` field in the JSON output. In Enrich Layer's Tools setup the advisor is `el-bot linear-rubric --advise`, the bot-suitability rubric: an issue it marks BOT gets `bot` **by default**, and an EXCLUDE issue is unchanged.
+
+- **Opt out for one create** with `--no-label-advisor` (for example, work you intend to do yourself, or an issue whose consent you are not in a position to give).
+- **Read the create output.** `labelAdvisor.added` lists what the advisor added; `labelAdvisor.consent` reports a consent label (`{labels, applied, repo, problem?}`). `applied: false` means the issue exists without that label, and `problem` says why.
+
+**Consent labels need a receipt.** Where `validation.consentReceiptGate` is on (Enrich Layer's shared config turns it on), a consent label (`validation.consentLabels`, default `bot`) is only valid with exactly one `<!-- el-intake-decision:v1 {...} -->` receipt in the description that names the issue — bot-layer intake silently skips a `bot` issue without one. So:
+
+- **Default route: let the advisor apply it.** When the advisor returns `bot` with its receipt fields, el-linear creates the issue and then, in one update, applies `bot` with a receipt naming the new issue and you (the acting Linear user) as `actor`.
+- **Never pass `--labels bot` on create.** It is refused: the receipt must name an issue that does not exist yet.
+- **Adding `bot` to an existing issue** needs the receipt in the same update, or the update is refused and the error names what is missing. Enrich Layer: run `el-bot linear-consent <ID> --automatic-implementation --reason "<why>"`, which writes the label and a valid receipt together. Elsewhere: `el-linear issues update <ID> --labels bot --description-file <body-ending-with-the-receipt>`.
+
+The gate has no override flag and ignores `--skip-validation`: it protects consent, not field hygiene.
+
+---
+
 ## User @Mentions
 
 Reference team members by name in comments. el-linear resolves both explicit `@name` tokens and bare capitalized references to proper Linear mentions.

package/dist/auth/oauth-storage.d.ts

@@ -1,4 +1,4 @@
-import type { OAuthActor } from "./oauth-client.js";
+import type { OAuthActor, OAuthScope } from "./oauth-client.js";
 export declare const OAUTH_STATE_VERSION = 1;
 /**
  * Persisted OAuth state. Mirrors what we got back from Linear's token
@@ -6,17 +6,19 @@ export declare const OAUTH_STATE_VERSION = 1;
  */
 export interface OAuthState {
     v: typeof OAUTH_STATE_VERSION;
+    /** Legacy state omits this and is treated as authorization_code. */
+    grantType?: "authorization_code" | "client_credentials";
     /** Linear OAuth actor tied to the access token. Defaults to user for legacy state. */
     actor?: OAuthActor;
     /** viewer.id returned after authorization; for actor=app this is the app user ID. */
     viewerId?: string;
     clientId: string;
     clientSecret?: string;
-    registeredRedirectUri: string;
+    registeredRedirectUri?: string;
     accessToken: string;
     refreshToken?: string;
     tokenType: string;
-    scopes: string[];
+    scopes: OAuthScope[];
     /** Unix epoch milliseconds; computed at write time from `expires_in`. */
     expiresAt: number;
     /** When we last fetched a token (for diagnostics). */

package/dist/auth/oauth-token.d.ts

@@ -37,6 +37,11 @@ interface RefreshTokensInput {
     clientSecret?: string;
     refreshToken: string;
 }
+interface ClientCredentialsInput {
+    clientId: string;
+    clientSecret: string;
+    scopes: readonly OAuthScope[];
+}
 interface RevokeTokenInput {
     accessToken: string;
 }
@@ -59,6 +64,8 @@ export declare function exchangeCodeForTokens(input: ExchangeCodeInput, fetchImp
  * refresh token, so we plumb both fields through.
  */
 export declare function refreshTokens(input: RefreshTokensInput, fetchImpl?: FetchLike, now?: () => number): Promise<ExchangeResult>;
+/** Obtain an app-user token without a browser or refresh token. */
+export declare function exchangeClientCredentials(input: ClientCredentialsInput, fetchImpl?: FetchLike, now?: () => number): Promise<ExchangeResult>;
 /**
  * Revoke an access token. Best-effort — we don't throw on transport
  * errors so callers can still clear local state.

package/dist/auth/oauth-token.js

@@ -121,6 +121,19 @@ export async function refreshTokens(input, fetchImpl = defaultFetch, now = Date.
     }
     return tokenResponseToResult(res, now());
 }
+/** Obtain an app-user token without a browser or refresh token. */
+export async function exchangeClientCredentials(input, fetchImpl = defaultFetch, now = Date.now) {
+    const res = await postForm(LINEAR_TOKEN_URL, {
+        grant_type: "client_credentials",
+        client_id: input.clientId,
+        client_secret: input.clientSecret,
+        scope: input.scopes.join(","),
+    }, fetchImpl);
+    if (typeof res.access_token !== "string" || res.access_token === "") {
+        throw new Error("OAuth client-credentials response missing `access_token`.");
+    }
+    return tokenResponseToResult(res, now());
+}
 /**
  * Revoke an access token. Best-effort — we don't throw on transport
  * errors so callers can still clear local state.

package/dist/auth/token-resolver.d.ts

@@ -38,6 +38,8 @@ export interface GetActiveAuthOptions {
     fetchImpl?: FetchLike;
     /** Test seam: override the wall-clock for refresh expiry checks. */
     now?: () => number;
+    /** Internal 401-recovery seam for client-credentials tokens. */
+    forceOAuthRenewal?: boolean;
 }
 /**
  * Resolve the credential for this invocation.

package/dist/auth/token-resolver.js

@@ -19,7 +19,7 @@ import { getApiToken } from "../utils/auth.js";
 import { sanitizeForLog } from "../utils/sanitize-for-log.js";
 import { withFileLock } from "./oauth-fs.js";
 import { oauthStatePath, readOAuthState, writeOAuthState, } from "./oauth-storage.js";
-import { refreshTokens, } from "./oauth-token.js";
+import { exchangeClientCredentials, refreshTokens, } from "./oauth-token.js";
 /**
  * Resolve the credential for this invocation.
  *
@@ -67,7 +67,9 @@ export async function getActiveAuth(options = {}) {
 export async function ensureFreshAccessToken(state, options = {}) {
     const now = options.now ?? Date.now;
     // Fast path: token is fresh; no lock, no refresh.
-    if (now() + 60_000 < state.expiresAt) {
+    const forceClientCredentialsRenewal = options.forceOAuthRenewal === true &&
+        state.grantType === "client_credentials";
+    if (!forceClientCredentialsRenewal && now() + 60_000 < state.expiresAt) {
         return state;
     }
     // Snapshot the target path ONCE so a profile switch between the
@@ -79,19 +81,32 @@ export async function ensureFreshAccessToken(state, options = {}) {
         // Re-read inside the lock — another process may have refreshed
         // while we were waiting. If so, use their result.
         const current = (await readOAuthState(targetPath)) ?? state;
-        if (now() + 60_000 < current.expiresAt) {
+        if (now() + 60_000 < current.expiresAt &&
+            (!forceClientCredentialsRenewal || current.obtainedAt > state.obtainedAt)) {
             return current;
         }
-        if (!current.refreshToken) {
+        if (current.grantType !== "client_credentials" && !current.refreshToken) {
             throw new Error("OAuth access token expired and no refresh token is stored. Re-run `el-linear init oauth`.");
         }
         let refreshed;
         try {
-            refreshed = await refreshTokens({
-                clientId: current.clientId,
-                clientSecret: current.clientSecret,
-                refreshToken: current.refreshToken,
-            }, options.fetchImpl, now);
+            if (current.grantType === "client_credentials") {
+                if (!current.clientSecret) {
+                    throw new Error("stored client credentials are missing client_secret");
+                }
+                refreshed = await exchangeClientCredentials({
+                    clientId: current.clientId,
+                    clientSecret: current.clientSecret,
+                    scopes: current.scopes,
+                }, options.fetchImpl, now);
+            }
+            else {
+                refreshed = await refreshTokens({
+                    clientId: current.clientId,
+                    clientSecret: current.clientSecret,
+                    refreshToken: current.refreshToken,
+                }, options.fetchImpl, now);
+            }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -99,7 +114,7 @@ export async function ensureFreshAccessToken(state, options = {}) {
             // so at source — defense in depth, in case a future caller
             // (or a wrapper that catches+rethrows) inserts an unsanitized
             // stage into the error chain (DEV-4065).
-            throw new Error(`OAuth refresh failed: ${sanitizeForLog(message)}. Re-run \`el-linear init oauth\` to re-authorize.`);
+            throw new Error(`OAuth token renewal failed: ${sanitizeForLog(message)}. Re-run \`el-linear init oauth\` to re-authorize.`);
         }
         const next = {
             ...current,

package/dist/commands/init/index.js

@@ -14,7 +14,7 @@
  * Skip is the default at every prompt. Only `init token` is required for a
  * first-time setup; everything else can be skipped and revisited later.
  */
-import { validateOAuthActor, } from "../../auth/oauth-client.js";
+import { validateOAuthActor, validateScopes, } from "../../auth/oauth-client.js";
 import { mergeAliasesIntoConfig, runAliasesImport, runAliasesStep, } from "./aliases.js";
 import { runDefaultsStep } from "./defaults.js";
 import { runOAuthRevoke, runOAuthStep } from "./oauth.js";
@@ -62,6 +62,10 @@ export function setupInitCommands(program) {
         .description("Authorize via OAuth 2.0 (PKCE) — alternative to a personal API token")
         .option("--force", "ignore existing tokens; re-authorize unconditionally")
         .option("--actor <actor>", "OAuth actor: user (default) or app for agents/service accounts", validateOAuthActor)
+        .option("--client-credentials", "use the browserless OAuth app-user client_credentials grant")
+        .option("--client-id <id>", "OAuth client id (non-secret)")
+        .option("--client-secret-env <name>", "environment variable containing the OAuth client secret", "LINEAR_OAUTH_CLIENT_SECRET")
+        .option("--scopes <scopes>", "comma- or space-separated OAuth scopes", (value) => validateScopes(value.split(/[,\s]+/).filter(Boolean)))
         .option("--revoke", "revoke and remove the stored OAuth tokens")
         .option("--no-browser", "skip the browser-open + localhost listener; paste the code manually")
         .option("--port <port>", "localhost callback port (default 8765)", (value) => Number.parseInt(value, 10))
@@ -73,8 +77,20 @@ export function setupInitCommands(program) {
             console.log(`  ${result.message}`);
             return;
         }
+        const clientSecret = options.clientCredentials
+            ? process.env[options.clientSecretEnv]?.trim()
+            : undefined;
+        if (options.clientCredentials &&
+            !clientSecret &&
+            !process.stdin.isTTY) {
+            throw new Error(`Client credentials require ${options.clientSecretEnv} in a non-interactive shell.`);
+        }
         await runOAuthStep({
             actor: options.actor,
+            clientCredentials: options.clientCredentials === true,
+            clientId: options.clientId,
+            clientSecret,
+            scopes: options.scopes,
             force: options.force ?? false,
             // commander's `--no-browser` produces `browser: false`.
             noBrowser: options.browser === false,

package/dist/commands/init/oauth.d.ts

@@ -18,7 +18,7 @@
  * revoke before doing anything else.
  */
 import { runLocalhostCallback } from "../../auth/oauth-callback.js";
-import { type OAuthActor } from "../../auth/oauth-client.js";
+import { type OAuthActor, type OAuthScope } from "../../auth/oauth-client.js";
 import { type OAuthState } from "../../auth/oauth-storage.js";
 import { type FetchLike } from "../../auth/oauth-token.js";
 interface ViewerResponse {
@@ -36,6 +36,14 @@ interface ViewerResponse {
 export interface OAuthStepOptions {
     /** OAuth actor mode: `user` (default) or `app` for agents/service accounts. */
     actor?: OAuthActor;
+    /** Use the browserless app-user client_credentials grant. */
+    clientCredentials?: boolean;
+    /** Non-secret client id override for client-credentials setup. */
+    clientId?: string;
+    /** Secret supplied by the command's named environment variable. */
+    clientSecret?: string;
+    /** Scope override for non-interactive client-credentials setup. */
+    scopes?: OAuthScope[];
     /** Force re-authorization even if existing state is valid. */
     force?: boolean;
     /** Skip the localhost listener; use the headless code-paste prompt. */

package/dist/commands/init/oauth.js

@@ -24,7 +24,7 @@ import { DEFAULT_CALLBACK_PATH, runLocalhostCallback, } from "../../auth/oauth-c
 import { ALL_SCOPES, buildAuthorizeUrl, DEFAULT_SCOPES, generatePkce, generateState, SCOPE_DESCRIPTIONS, validateActorScopes, validateScopes, } from "../../auth/oauth-client.js";
 import { promptForPastedCode } from "../../auth/oauth-headless.js";
 import { clearOAuthState, OAUTH_STATE_VERSION, readOAuthState, writeOAuthState, } from "../../auth/oauth-storage.js";
-import { exchangeCodeForTokens, revokeToken, } from "../../auth/oauth-token.js";
+import { exchangeClientCredentials, exchangeCodeForTokens, revokeToken, } from "../../auth/oauth-token.js";
 import { GraphQLService } from "../../utils/graphql-service.js";
 import { sanitizeForLog } from "./token.js";
 const DEFAULT_PORT = 8765;
@@ -117,7 +117,7 @@ async function handleExistingState(existing, options) {
 function extractPortFromRedirect(state) {
     if (!state)
         return null;
-    const match = state.registeredRedirectUri.match(/:(\d+)\//);
+    const match = state.registeredRedirectUri?.match(/:(\d+)\//);
     if (!match)
         return null;
     const n = Number.parseInt(match[1], 10);
@@ -196,6 +196,30 @@ async function resolveRegistration(defaults) {
         scopes: teamConfig.scopes,
     };
 }
+async function resolveClientCredentialsRegistration(options) {
+    if (options.actor && options.actor !== "app") {
+        throw new Error("--client-credentials requires --actor app.");
+    }
+    const teamConfig = await readTeamOAuthConfig();
+    if (teamConfig && teamConfig.actor !== "app") {
+        throw new Error(`${teamConfig.sourcePath} configures actor=user; client credentials require an OAuth app configured for actor=app.`);
+    }
+    const clientId = options.clientId?.trim() ||
+        teamConfig?.clientId ||
+        (await input({
+            message: "Linear OAuth client_id:",
+            validate: (value) => value.trim().length > 0 || "client_id cannot be empty",
+        })).trim();
+    const clientSecret = options.clientSecret?.trim() ||
+        (await password({
+            message: "Linear OAuth client_secret (required, hidden):",
+            mask: "*",
+            validate: (value) => value.trim().length > 0 || "client_secret cannot be empty",
+        })).trim();
+    const scopes = validateScopes(options.scopes ?? teamConfig?.scopes ?? [...DEFAULT_SCOPES]);
+    validateActorScopes("app", scopes);
+    return { clientId, clientSecret, scopes };
+}
 /**
  * Default viewer-validation routine. Calls `viewer { ... }` with the new
  * bearer token to confirm Linear accepted it. Reused for both the wizard
@@ -226,7 +250,14 @@ async function defaultValidateViewer(oauthToken) {
 export async function runOAuthStep(options = {}) {
     const validateViewer = options.validateViewer ?? defaultValidateViewer;
     const existing = await readOAuthState();
-    if (existing && !options.force) {
+    const requestedGrant = options.clientCredentials
+        ? "client_credentials"
+        : "authorization_code";
+    const existingGrant = existing?.grantType ?? "authorization_code";
+    if (existing && existingGrant !== requestedGrant && !options.force) {
+        throw new Error(`This profile already stores ${existingGrant} OAuth state. Re-run with --force to replace it with ${requestedGrant}.`);
+    }
+    if (existing && existingGrant === requestedGrant && !options.force) {
         const handled = await handleExistingState(existing, options);
         if (handled.kind === "keep") {
             // Validate the existing token actually works; if it's already
@@ -244,6 +275,33 @@ export async function runOAuthStep(options = {}) {
         }
         // Both `reauth` and `revoked` fall through to the re-auth flow.
     }
+    if (options.clientCredentials) {
+        const reg = await resolveClientCredentialsRegistration(options);
+        logLine(TS("Requesting an app-user token with client credentials…"));
+        const exchanged = await exchangeClientCredentials({
+            clientId: reg.clientId,
+            clientSecret: reg.clientSecret,
+            scopes: reg.scopes,
+        }, options.fetchImpl);
+        const newState = {
+            v: OAUTH_STATE_VERSION,
+            grantType: "client_credentials",
+            actor: "app",
+            clientId: reg.clientId,
+            clientSecret: reg.clientSecret,
+            accessToken: exchanged.accessToken,
+            tokenType: exchanged.tokenType,
+            scopes: exchanged.scopes.length > 0 ? exchanged.scopes : reg.scopes,
+            expiresAt: exchanged.expiresAt,
+            obtainedAt: Date.now(),
+        };
+        logLine(TS("Validating against viewer…"));
+        const viewer = await validateViewer(newState.accessToken);
+        newState.viewerId = viewer.id;
+        await writeOAuthState(newState);
+        logLine(TS(`✓ Authorized app user ${viewer.displayName} <${viewer.email}> (${viewer.organization.name}).`));
+        return { state: newState, viewer };
+    }
     const reg = await resolveRegistration({
         actor: options.actor,
         manualPort: options.port ?? extractPortFromRedirect(existing) ?? DEFAULT_PORT,
@@ -308,6 +366,7 @@ export async function runOAuthStep(options = {}) {
     }, options.fetchImpl);
     const newState = {
         v: OAUTH_STATE_VERSION,
+        grantType: "authorization_code",
         actor: reg.actor,
         clientId: reg.clientId,
         clientSecret: reg.clientSecret,