@enrichlayer/el-linear 1.9.0 → 1.15.0

package/README.md

@@ -68,7 +68,7 @@ every team ends up writing themselves:
 | **Term enforcement** | Catch misspellings of brand and project names in issue titles and descriptions ("EnrichLayer" → "Enrich Layer"). |
 | **Status defaults** | "No project? → Triage. Has assignee+project? → Todo." Per-workspace, configurable. |
 | **Auto-link & relate** | When you write `EMW-258` in a description, el-linear wraps it as a markdown link **and** creates the corresponding sidebar relation. Prose like "blocked by EMW-258" infers the relation type. |
-| **`--claude` flag** | Tag issues delegated to [Claude Code](https://claude.ai/code) for autonomous work. The label is plain config; the flag is muscle memory. |
+| **Agent delegation** | Use Linear's native `delegate` field for agent work while keeping the human `assignee` responsible. `issues start` moves work to the team's first started status. |
 | **GraphQL escape hatch** | Anything not covered by built-in commands: `el-linear graphql '{ viewer { id } }'`. Schema introspection included. |
 | **Bundled Claude skill** | The published tarball includes a `claude-skills/linear-operations/` directory you can symlink into your project's `.claude/skills/`. |
 
@@ -89,6 +89,7 @@ or pointing `EL_LINEAR_OAUTH_CONFIG` at one:
 ```json
 {
   "linearOAuth": {
+    "actor": "user",
     "clientId": "your-linear-oauth-client-id",
     "redirectPort": 8765,
     "scopes": ["read", "write", "issues:create", "comments:create"],
@@ -101,6 +102,15 @@ or pointing `EL_LINEAR_OAUTH_CONFIG` at one:
 not execute password-manager commands from it. Do not put a `client_secret` in
 this shared file. The OAuth flow uses PKCE.
 
+For agent/service-account OAuth, authorize the app actor:
+
+```bash
+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`.
+
 At runtime, credentials are resolved in this order:
 
 1. `--api-token <token>` flag.
@@ -237,6 +247,102 @@ A full reference with every key documented lives in [config.example.json](./conf
 UUIDs come from the Linear UI (URL bars, settings pages) or via el-linear
 itself: `el-linear teams list --raw | jq '.[] | {key, id}'`, etc.
 
+### Workspace URL key
+
+`refs wrap` and the auto-link paths build canonical issue URLs like
+`https://linear.app/<workspaceUrlKey>/issue/<id>/`. By default the key is
+fetched once per CLI invocation via `viewer.organization.urlKey`. To skip the
+network call (offline use, perf, `--no-validate`), provide it via any of:
+
+1. `--workspace-url-key <key>` flag on `refs wrap` (per-invocation, highest priority)
+2. `EL_LINEAR_WORKSPACE_URL_KEY` env var
+3. `workspaceUrlKey` field in `config.json`
+
+When any of these is set, no GraphQL request is made.
+
+### Shared team config
+
+Teams can check a shared config file into a repository (e.g. a Tools repo) and
+have every member load it automatically. The team file holds things that are the
+same for everyone — member aliases, label maps, term rules, validation settings —
+while personal config holds individual preferences and tokens.
+
+**Merge order (lowest → highest priority):**
+
+1. Built-in defaults
+2. Team config file
+3. Personal `~/.config/el-linear/config.json` (or profile config)
+
+Personal config wins on scalar conflicts. Arrays (`terms`, `defaultLabels`) are
+**concatenated** — personal entries are appended to team entries, so you extend
+the team rules rather than replace them.
+
+**Set the team config path** with the `config team` subcommand — it
+resolves relative / `~/...` paths, validates the file before writing, and
+performs an atomic file-locked update:
+
+```bash
+el-linear config team set-path /path/to/tools-repo/.el-linear/config.json
+el-linear config team show     # confirm path + the keys it contributes
+el-linear config team clear    # remove the pointer
+```
+
+The command writes `teamConfigPath` into your personal `config.json`, so
+the setting persists across shells. To override the persistent setting
+per-invocation, use the `EL_LINEAR_TEAM_CONFIG` env var (highest
+priority):
+
+```bash
+EL_LINEAR_TEAM_CONFIG=/path/to/tools-repo/.el-linear/config.json el-linear issues create ...
+```
+
+If you prefer to edit the personal config by hand, the field looks like:
+
+```json
+{ "teamConfigPath": "/path/to/tools-repo/.el-linear/config.json" }
+```
+
+— but the CLI path is preferred (it catches missing-file and invalid-JSON
+mistakes before they silently fall back to no team layer).
+
+**Auto-discovery from an onboarding marker.** As a third fallback, when
+neither the env var nor `teamConfigPath` is set, `el-linear` reads
+`~/.config/el-tools-root` (written by EL onboarding's `link-project.sh`)
+and uses `<root>/config/el-linear.shared.json` if it exists. This means
+developers who've already run onboarding get the team layer for free —
+no extra `set-path` step. The marker is the opt-in consent signal; users
+without it (the OSS audience) see no behavior change. Resolution order
+in full:
+
+1. `EL_LINEAR_TEAM_CONFIG` env var
+2. `teamConfigPath` in personal `config.json`
+3. `~/.config/el-tools-root` marker → `<root>/config/el-linear.shared.json`
+
+`el-linear config team show` reports which of these resolved (`source`
+field: `env` / `personal` / `marker` / `null`).
+
+**The team config file** is a standard `config.json` fragment — any `ElLinearConfig`
+field is valid except `teamConfigPath` itself. Keep it free of tokens and personal
+preferences; those stay in personal config. Example team file:
+
+```json
+{
+  "members": {
+    "aliases": { "alice": "Alice Anderson", "bob": "Bob Barnes" },
+    "uuids":   { "Alice Anderson": "<uuid>",  "Bob Barnes": "<uuid>" }
+  },
+  "teams": { "ENG": "<uuid>", "OPS": "<uuid>" },
+  "labels": { "workspace": { "claude": "<uuid>" } },
+  "terms": [
+    { "canonical": "Enrich Layer", "reject": ["EnrichLayer", "enrichlayer"] }
+  ],
+  "validation": { "enabled": true }
+}
+```
+
+Run `el-linear config show` to see the resolved config and confirm which team
+config path is active (`teamConfig` field in the output).
+
 ## Term enforcement (with brand-promotion examples)
 
 The `terms` rules let you keep a list of canonical names and the misspellings
@@ -264,20 +370,23 @@ are allowed even though `enrichlayer` is rejected.
 
 If you don't define any rules, term enforcement is a no-op.
 
-## The `--claude` delegation pattern
+## Native Agent Delegation
 
-`el-linear issues create` accepts `--claude`, which applies the workspace label
-configured at `config.labels.workspace.claude`. The label is the contract:
-it tells [Claude Code](https://claude.ai/code) "this issue is delegated to
-you for autonomous execution."
+Linear now has a native issue `delegate` field for agent work. Use `assignee`
+for the accountable human and `delegate` for the agent app user doing the
+implementation.
 
 ```bash
 el-linear issues create "Migrate auth middleware to new session store" \
-  --team ENG --assignee alice --project "Auth Refactor" \
-  --description "..." --claude
+  --team ENG --assignee alice --delegate claude --project "Auth Refactor" \
+  --description "..."
+
+el-linear issues start ENG-123
 ```
 
-Claude finds delegated work with `el-linear issues search "claude" --status "Todo"`.
+Agents find delegated work with `el-linear issues list --delegate claude`.
+`--claude` still applies the legacy configured label, but native `--delegate`
+is the preferred contract.
 
 ## Commands at a glance
 
@@ -288,7 +397,7 @@ el-linear <command> --help       # detailed help for one command
 
 | Group | Common commands |
 |-------|-----------------|
-| Issues | `issues {list, search, create, read, update, delete, history, related, link-references}` |
+| Issues | `issues {list, search, create, read, update, start, delete, history, related, link-references}` |
 | Comments | `comments {list, create, update}` |
 | Labels | `labels {list, create, retire, restore}` |
 | Projects | `projects {list, add-team, remove-team}` |
@@ -372,6 +481,26 @@ global `summary` value works on every read/list command.
 `--raw` together with `--format summary` to render a list envelope as a
 bare item-list rather than an envelope.
 
+### Extract a single description section: `--field`
+
+`issues read --field <name>` extracts one named section from an issue's
+markdown description and prints just that section's text — no JSON
+envelope. Matches `##`/`###` headers and bold pseudo-headers
+(`**Done when**`) case-insensitively. Returns exit code 1 with a stderr
+message when the section is missing.
+
+```bash
+el-linear issues read DEV-123 --field "Done when"
+# - Thing A
+# - Thing B
+
+el-linear read ADM-652 --field "Out of scope"
+# Stuff we won't do.
+```
+
+Single-issue only — pair it with `--jq` on full JSON for batch
+extraction across many issues.
+
 ## Wrapping Linear references in arbitrary text
 
 `el-linear refs wrap` takes plain text on stdin (or via `--file`) and rewrites

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

@@ -58,6 +58,24 @@ el-linear issues read DEV-123 --format summary 2>&1
 
 The summary formatter exists exactly because every consumer (humans and LLMs) was reinventing the same `python -c` / `jq` extraction in shell. Pick the canonical path; the per-resource format is a stable contract.
 
+### Extracting one description section: `--field`
+
+When you need a single named section out of an issue's markdown description (e.g. "Done when", "Out of scope", "Why we need this"), use `issues read --field`. It matches `##`/`###` headers and bold pseudo-headers (`**Done when**`) case-insensitively, prints just that section's text, and exits non-zero when the section is missing — the canonical replacement for piping into `python3 -c "...desc.find(...)"`.
+
+```bash
+# ✅ One section, plain text, scriptable
+el-linear issues read DEV-123 --field "Done when" 2>&1
+
+# ❌ Don't do this
+el-linear issues read DEV-123 2>&1 | python3 -c "import json,sys; print(json.load(sys.stdin)['description'].split('## Done when')[1].split('##')[0])"
+```
+
+`--field` is single-issue only — for batch extraction, fall back to `--jq` on the full JSON.
+
+### When you must reach outside el-linear: prefer `jq` over `python3 -c`
+
+For tools that aren't `el-linear` (e.g. `gh`, `glab`, `kubectl`), prefer `jq` for JSON extraction in one-shot shell commands. `python3 -c "import json,sys; ..."` produces longer, harder-to-read pipelines, and tends to attract incremental complexity (try/except, fallbacks) that `jq` handles inline. Reach for python only when the transformation genuinely needs control flow that's painful in `jq` (e.g. multi-step assembly with intermediate state).
+
 ### Coverage
 
 `--format summary` is implemented for:
@@ -129,6 +147,24 @@ el-linear issues related ENG-123 2>&1
 
 Returns all relations (related, blocks, blockedBy, duplicate) with direction, state, and assignee. Use this before creating follow-up work to understand the context around an issue.
 
+### Adding relations to an existing issue
+
+To attach a relation to an issue that **already exists** (triage, splitting findings into separate issues, backfilling related work), use `issues relate` — or pass the same flags to `issues update`:
+
+```bash
+# Dedicated relation command
+el-linear issues relate ENG-123 --related-to "ENG-456,ENG-789" 2>&1
+el-linear issues relate ENG-123 --blocked-by "ENG-400" 2>&1
+el-linear issues relate ENG-123 --duplicate-of "ENG-111" 2>&1
+
+# Or alongside a field update in one call
+el-linear issues update ENG-123 --status "In Progress" --related-to "ENG-456" 2>&1
+```
+
+Both `issues relate` and `issues update` accept `--related-to`, `--blocks`, `--blocked-by`, and `--duplicate-of` (comma-separated identifiers; `--duplicate-of` takes a single issue). `issues create` accepts the same flags.
+
+> **Gotcha:** `--related-to` is **not** valid on `issues update` in el-linear < 1.12. On older versions it fails with `error: unknown option '--related-to'` — use `el-linear issues relate <id> --related-to …` instead. `issues relate` has always supported it.
+
 ### Auto-linking issue references on create/update
 
 `el-linear issues create`, `el-linear issues update`, `el-linear comments create`, and `el-linear comments update` run the same auto-linking flow on text being written:
@@ -333,7 +369,11 @@ el-linear projects add-team "Project Name" ENG 2>&1
 
 ### Discovery Before Creation
 
-Always check if a project exists before creating: `el-linear projects list --limit 50`.
+Always check if a project exists before creating: `el-linear projects list`.
+
+The CLI emits a `results_truncated` warning in `_warnings` when the result set hits `--limit` — bump `--limit` (the suggested next size is in the warning text) or narrow via `--name` / `--state` and retry. Linear URLs and bare slug-ids (`https://linear.app/<workspace>/project/<slug>-<12-hex>/...` or bare `<slug>-<12-hex>`) resolve directly when passed to `--project` — no need to extract a human-readable name yourself.
+
+**If the user names a project that doesn't surface, do not substitute a different one.** Broaden the search (drop `--state` / `--active` / `--name` filters, then bump `--limit`); if it still doesn't appear, **ask** the user before falling back. Substituting a wrong project silently is worse than asking one extra question.
 
 ---
 

package/dist/auth/linear-credential.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared credential shape consumed by the Linear-talking service classes
+ * (`GraphQLService`, `LinearService`, `FileService`). Pre-DEV-4068 T7,
+ * each service declared its own `*ServiceAuth` type — three byte-identical
+ * unions plus a deprecated `string` arm that only tests exercised. The
+ * three duplicates would inevitably drift; the single shared shape forces
+ * lock-step.
+ *
+ * The discriminant is structural — TypeScript narrows on `"apiKey" in
+ * auth` vs `"oauthToken" in auth`. An explicit `kind` tag would force
+ * every call site (including ~40 tests) to thread it through; the
+ * structural form keeps the existing `{ apiKey: "..." }` /
+ * `{ oauthToken: "..." }` literal usage working unchanged.
+ *
+ * The runtime difference between the two arms is the `Authorization`
+ * header shape:
+ *   - apiKey:    `Authorization: <token>`        (no Bearer prefix)
+ *   - oauthToken: `Authorization: Bearer <token>`
+ *
+ * The `string` arm was dropped — tests now construct with
+ * `{ apiKey: "test-token" }` (mechanical rewrite, no semantic change).
+ */
+export type LinearCredential = {
+    apiKey: string;
+} | {
+    oauthToken: string;
+};

package/dist/auth/linear-credential.js

@@ -0,0 +1 @@
+export {};

package/dist/auth/oauth-app-config.d.ts

@@ -5,9 +5,9 @@
  * materialize it from a password manager, while the OSS CLI keeps requiring
  * users to bring their own OAuth app when no local file exists.
  */
-import { type OAuthScope } from "./oauth-client.js";
-export declare const TEAM_OAUTH_CONFIG_ENV = "EL_LINEAR_OAUTH_CONFIG";
-export interface TeamOAuthConfig {
+import { type OAuthActor, type OAuthScope } from "./oauth-client.js";
+interface TeamOAuthConfig {
+    actor: OAuthActor;
     clientId: string;
     redirectPort: number;
     scopes: OAuthScope[];
@@ -19,3 +19,4 @@ export interface TeamOAuthConfig {
     sourcePath: string;
 }
 export declare function readTeamOAuthConfig(env?: NodeJS.ProcessEnv): Promise<TeamOAuthConfig | null>;
+export {};

package/dist/auth/oauth-app-config.js

@@ -7,8 +7,8 @@
  */
 import fs from "node:fs/promises";
 import { TEAM_OAUTH_CONFIG_PATH } from "../config/paths.js";
-import { DEFAULT_SCOPES, validateScopes, } from "./oauth-client.js";
-export const TEAM_OAUTH_CONFIG_ENV = "EL_LINEAR_OAUTH_CONFIG";
+import { DEFAULT_SCOPES, validateActorScopes, validateOAuthActor, validateScopes, } from "./oauth-client.js";
+const TEAM_OAUTH_CONFIG_ENV = "EL_LINEAR_OAUTH_CONFIG";
 export async function readTeamOAuthConfig(env = process.env) {
     const envPath = env[TEAM_OAUTH_CONFIG_ENV]?.trim();
     const sourcePath = envPath || TEAM_OAUTH_CONFIG_PATH;
@@ -43,8 +43,11 @@ export async function readTeamOAuthConfig(env = process.env) {
     }
     const redirectPort = parseRedirectPort(linearOAuth.redirectPort, sourcePath);
     const scopes = parseScopes(linearOAuth.scopes, sourcePath);
+    const actor = parseActor(linearOAuth.actor, sourcePath);
+    validateActorScopes(actor, scopes);
     const passwordManagerPath = parsePasswordManagerPath(linearOAuth.passwordManagerPath, sourcePath);
     return {
+        actor,
         clientId,
         redirectPort,
         scopes,
@@ -52,6 +55,14 @@ export async function readTeamOAuthConfig(env = process.env) {
         sourcePath,
     };
 }
+function parseActor(value, sourcePath) {
+    if (value === undefined)
+        return "user";
+    if (typeof value !== "string") {
+        throw new Error(`${sourcePath} linearOAuth.actor must be "user" or "app".`);
+    }
+    return validateOAuthActor(value);
+}
 function parseRedirectPort(value, sourcePath) {
     if (value === undefined)
         return 8765;

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

@@ -18,9 +18,7 @@
 import { type Server } from "node:http";
 import { type CallbackParams } from "./oauth-client.js";
 export declare const DEFAULT_CALLBACK_PATH = "/oauth/callback";
-export declare const DEFAULT_LISTEN_HOST = "127.0.0.1";
-export declare const DEFAULT_TIMEOUT_MS: number;
-export interface CallbackOptions {
+interface CallbackOptions {
     port: number;
     expectedState: string;
     host?: string;
@@ -38,3 +36,4 @@ export interface CallbackOptions {
  * CI).
  */
 export declare function runLocalhostCallback(options: CallbackOptions, serverFactory?: () => Server): Promise<CallbackParams>;
+export {};

package/dist/auth/oauth-callback.js

@@ -18,8 +18,8 @@
 import { createServer } from "node:http";
 import { parseCallbackUrl } from "./oauth-client.js";
 export const DEFAULT_CALLBACK_PATH = "/oauth/callback";
-export const DEFAULT_LISTEN_HOST = "127.0.0.1";
-export const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_LISTEN_HOST = "127.0.0.1";
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
 const SUCCESS_HTML = `<!doctype html>
 <html lang="en">
 <head><meta charset="utf-8"><title>el-linear · authorized</title>

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

@@ -3,11 +3,12 @@ export declare const DEFAULT_SCOPES: readonly OAuthScope[];
 /** All scopes Linear advertises. Keep in sync with their docs. */
 export declare const ALL_SCOPES: readonly ["read", "write", "issues:create", "comments:create", "timeSchedule:write", "admin", "app:assignable", "app:mentionable"];
 export type OAuthScope = (typeof ALL_SCOPES)[number];
+export type OAuthActor = "user" | "app";
 export declare const SCOPE_DESCRIPTIONS: Record<OAuthScope, string>;
 export declare const LINEAR_AUTHORIZE_URL = "https://linear.app/oauth/authorize";
 export declare const LINEAR_TOKEN_URL = "https://api.linear.app/oauth/token";
 export declare const LINEAR_REVOKE_URL = "https://api.linear.app/oauth/revoke";
-export interface PkcePair {
+interface PkcePair {
     verifier: string;
     challenge: string;
     method: "S256";
@@ -22,12 +23,14 @@ export interface PkcePair {
 export declare function generatePkce(): PkcePair;
 /** Cryptographically random `state` parameter. 16 bytes → 22-char b64url. */
 export declare function generateState(): string;
-export interface AuthorizeUrlInput {
+interface AuthorizeUrlInput {
     clientId: string;
     redirectUri: string;
     scopes: readonly string[];
     state: string;
     codeChallenge: string;
+    /** `app` makes mutations appear as the OAuth app user. */
+    actor?: OAuthActor;
     /** "consent" forces the consent screen even for previously-authorized users. */
     prompt?: "consent";
 }
@@ -53,3 +56,6 @@ export declare function parseCallbackUrl(rawUrl: string): CallbackParams;
  * tuple; throws on any unknown scope (typo guard).
  */
 export declare function validateScopes(scopes: readonly string[]): OAuthScope[];
+export declare function validateOAuthActor(value: string | undefined): OAuthActor;
+export declare function validateActorScopes(actor: OAuthActor, scopes: readonly OAuthScope[]): void;
+export {};

package/dist/auth/oauth-client.js

@@ -35,6 +35,10 @@ export const ALL_SCOPES = [
     "app:assignable",
     "app:mentionable",
 ];
+const APP_ONLY_SCOPES = new Set([
+    "app:assignable",
+    "app:mentionable",
+]);
 export const SCOPE_DESCRIPTIONS = {
     read: "Read access to the user's account.",
     write: "Write access. Without admin, also requires issues:create / comments:create for those mutations.",
@@ -86,6 +90,9 @@ export function buildAuthorizeUrl(input) {
     url.searchParams.set("state", input.state);
     url.searchParams.set("code_challenge", input.codeChallenge);
     url.searchParams.set("code_challenge_method", "S256");
+    if (input.actor && input.actor !== "user") {
+        url.searchParams.set("actor", input.actor);
+    }
     if (input.prompt) {
         url.searchParams.set("prompt", input.prompt);
     }
@@ -132,3 +139,22 @@ export function validateScopes(scopes) {
     }
     return out;
 }
+export function validateOAuthActor(value) {
+    if (!value) {
+        return "user";
+    }
+    const trimmed = value.trim().toLowerCase();
+    if (trimmed === "user" || trimmed === "app") {
+        return trimmed;
+    }
+    throw new Error('OAuth actor must be either "user" or "app".');
+}
+export function validateActorScopes(actor, scopes) {
+    if (actor === "app" && scopes.includes("admin")) {
+        throw new Error('OAuth actor "app" cannot request the admin scope. Remove admin or use actor "user".');
+    }
+    const hasAppOnlyScope = scopes.some((scope) => APP_ONLY_SCOPES.has(scope));
+    if (actor !== "app" && hasAppOnlyScope) {
+        throw new Error('Scopes app:assignable/app:mentionable require OAuth actor "app". Re-run with `--actor app` or set linearOAuth.actor to "app".');
+    }
+}

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

@@ -1,5 +1,5 @@
 export declare function atomicWrite(targetPath: string, data: string | Uint8Array, mode?: number): Promise<void>;
-export interface FileLockOptions {
+interface FileLockOptions {
     /** Treat a lock older than this as crashed and steal it. Default 30s. */
     staleAfterMs?: number;
     /** Maximum time to wait for the lock before giving up. Default 30s. */
@@ -21,3 +21,4 @@ export interface FileLockOptions {
  * anyway).
  */
 export declare function withFileLock<T>(targetPath: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+export {};

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

@@ -16,7 +16,7 @@
  * whether the URL is reachable.
  */
 import { type CallbackParams } from "./oauth-client.js";
-export interface PromptForPastedCodeOptions {
+interface PromptForPastedCodeOptions {
     expectedState: string;
     /**
      * Allow the user to paste a bare authorization code without a
@@ -41,3 +41,4 @@ export interface PromptForPastedCodeOptions {
  * behalf. Opt in with `--unsafe-bare-code` (`unsafeBareCode: true`).
  */
 export declare function promptForPastedCode(options: PromptForPastedCodeOptions): Promise<CallbackParams>;
+export {};

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

@@ -1,11 +1,15 @@
+import type { OAuthActor } from "./oauth-client.js";
 export declare const OAUTH_STATE_VERSION = 1;
-export declare const OAUTH_STATE_FILENAME = "oauth.json";
 /**
  * Persisted OAuth state. Mirrors what we got back from Linear's token
  * endpoint plus the bits we need to refresh / re-authorize.
  */
 export interface OAuthState {
     v: typeof OAUTH_STATE_VERSION;
+    /** 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;

package/dist/auth/oauth-storage.js

@@ -15,7 +15,7 @@ import path from "node:path";
 import { CONFIG_DIR, resolveActiveProfile } from "../config/paths.js";
 import { atomicWrite } from "./oauth-fs.js";
 export const OAUTH_STATE_VERSION = 1;
-export const OAUTH_STATE_FILENAME = "oauth.json";
+const OAUTH_STATE_FILENAME = "oauth.json";
 /**
  * Resolve the path to the active profile's `oauth.json`. Mirrors
  * `activePaths()` in `commands/init/shared.ts` so OAuth state lands in the

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

@@ -25,19 +25,19 @@ export type FetchLike = (url: string, init: {
     statusText: string;
     text(): Promise<string>;
 }>;
-export interface ExchangeCodeInput {
+interface ExchangeCodeInput {
     clientId: string;
     clientSecret?: string;
     code: string;
     redirectUri: string;
     codeVerifier: string;
 }
-export interface RefreshTokensInput {
+interface RefreshTokensInput {
     clientId: string;
     clientSecret?: string;
     refreshToken: string;
 }
-export interface RevokeTokenInput {
+interface RevokeTokenInput {
     accessToken: string;
 }
 export interface ExchangeResult {
@@ -68,3 +68,4 @@ export declare function revokeToken(input: RevokeTokenInput, fetchImpl?: FetchLi
     status: number;
     message?: string;
 }>;
+export {};

package/dist/auth/oauth-token.js

@@ -10,6 +10,7 @@
  * caller injects is the URL fetcher, so tests can mock without touching the
  * network.
  */
+import { sanitizeForLog } from "../utils/sanitize-for-log.js";
 import { LINEAR_REVOKE_URL, LINEAR_TOKEN_URL, } from "./oauth-client.js";
 const defaultFetch = async (url, init) => {
     const res = await globalThis.fetch(url, init);
@@ -42,13 +43,19 @@ async function postForm(url, params, fetchImpl) {
     if (!res.ok) {
         // Don't dump the request body — it contains client_secret /
         // refresh_token / authorization code, all of which are secrets.
-        throw new Error(`OAuth endpoint ${url} responded ${res.status} ${res.statusText}: ${text || "(empty body)"}`);
+        // Sanitize the response body at source too: an MITM, misconfigured
+        // proxy, or buggy upstream that echoes the request headers back in
+        // its error body would otherwise leak `Bearer <token>` into the
+        // error chain. Defense in depth on top of outputError's
+        // sanitization (DEV-4065).
+        const safe = sanitizeForLog(text || "(empty body)");
+        throw new Error(`OAuth endpoint ${url} responded ${res.status} ${res.statusText}: ${safe}`);
     }
     try {
         return JSON.parse(text);
     }
     catch {
-        throw new Error(`OAuth endpoint ${url} returned non-JSON response: ${text.slice(0, 200)}`);
+        throw new Error(`OAuth endpoint ${url} returned non-JSON response: ${sanitizeForLog(text.slice(0, 200))}`);
     }
 }
 function parseScopes(raw) {
@@ -128,14 +135,19 @@ export async function revokeToken(input, fetchImpl = defaultFetch) {
             },
             body: "",
         });
+        // Sanitize at source for symmetry with postForm's error branch — a
+        // misconfigured proxy that echoes the request's Authorization header
+        // in its 5xx body would otherwise surface the bearer token through
+        // `message`. The two call sites in `commands/init/oauth.ts` already
+        // re-sanitize at emission, but defense in depth (DEV-4065).
         return {
             ok: res.ok,
             status: res.status,
-            message: res.ok ? undefined : await res.text(),
+            message: res.ok ? undefined : sanitizeForLog(await res.text()),
         };
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        return { ok: false, status: 0, message };
+        return { ok: false, status: 0, message: sanitizeForLog(message) };
     }
 }

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

@@ -17,12 +17,21 @@
  */
 import { type OAuthState } from "./oauth-storage.js";
 import { type FetchLike } from "./oauth-token.js";
-export interface ActiveAuth {
-    kind: "personal" | "oauth";
+/**
+ * Resolved credential for a CLI invocation. Discriminated on `kind` so
+ * `oauth` is non-optional in the `"oauth"` arm and forbidden in the
+ * `"personal"` arm — eliminates the "personal auth with stale oauth field"
+ * foot-gun the flat shape allowed.
+ */
+export type ActiveAuth = {
+    kind: "personal";
     token: string;
-    /** Original OAuth state, when `kind === "oauth"`. */
-    oauth?: OAuthState;
-}
+} | {
+    kind: "oauth";
+    token: string;
+    /** Original OAuth state — refresh-time bookkeeping. */
+    oauth: OAuthState;
+};
 export interface GetActiveAuthOptions {
     apiToken?: string;
     /** Test seam: override the network fetcher used by refresh. */

package/dist/auth/token-resolver.js

@@ -16,6 +16,7 @@
  *   - oauth:     `Authorization: Bearer <token>`
  */
 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";
@@ -94,7 +95,11 @@ export async function ensureFreshAccessToken(state, options = {}) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            throw new Error(`OAuth refresh failed: ${message}. Re-run \`el-linear init oauth\` to re-authorize.`);
+            // Sanitize again here even though refreshTokens already does
+            // 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.`);
         }
         const next = {
             ...current,