@enrichlayer/el-linear 1.6.0 → 1.9.0

package/README.md

@@ -74,13 +74,41 @@ every team ends up writing themselves:
 
 ## Authentication
 
-The API token is resolved in this order:
+el-linear supports either OAuth or a personal Linear API token. OAuth is
+configured with:
+
+```bash
+el-linear init oauth
+```
+
+By default, that command walks you through registering your own Linear OAuth
+app. Teams can make the flow a single browser authorization step by writing a
+local, untracked app-defaults file at `~/.config/el-linear/team-oauth.json`
+or pointing `EL_LINEAR_OAUTH_CONFIG` at one:
+
+```json
+{
+  "linearOAuth": {
+    "clientId": "your-linear-oauth-client-id",
+    "redirectPort": 8765,
+    "scopes": ["read", "write", "issues:create", "comments:create"],
+    "passwordManagerPath": "op://vault/item/client_id"
+  }
+}
+```
+
+`passwordManagerPath` is optional metadata for humans/scripts; el-linear does
+not execute password-manager commands from it. Do not put a `client_secret` in
+this shared file. The OAuth flow uses PKCE.
+
+At runtime, credentials are resolved in this order:
 
 1. `--api-token <token>` flag.
 2. `LINEAR_API_TOKEN` environment variable.
-3. **Active profile's** `~/.config/el-linear/profiles/<name>/token` file (see *Profiles* below).
-4. `~/.config/el-linear/token` file (legacy single-profile, recommended for human use when only one workspace is needed).
-5. `~/.linear_api_token` file (legacy, still honored).
+3. **Active profile's** OAuth state (`oauth.json`) from `el-linear init oauth`.
+4. **Active profile's** `~/.config/el-linear/profiles/<name>/token` file (see *Profiles* below).
+5. `~/.config/el-linear/token` file (legacy single-profile, recommended for human use when only one workspace is needed).
+6. `~/.linear_api_token` file (legacy, still honored).
 
 el-linear never logs the token.
 
@@ -274,7 +302,75 @@ el-linear <command> --help       # detailed help for one command
 | Config | `config show`, `users list`, `teams list`, `templates list` |
 
 All `list` subcommands support `-l, --limit <n>`. All commands accept the
-top-level filters: `--raw`, `--jq <expr>`, `--fields <list>`.
+top-level filters: `--format <json|summary>`, `--raw`, `--jq <expr>`, `--fields <list>`.
+
+## Output formats
+
+Every command accepts `--format <kind>` at the root:
+
+- `--format json` (default) — emits the full structured envelope. Stable
+  shape across releases. Composes with `--jq`, `--fields`, and `--raw`.
+- `--format summary` — emits a fixed human-readable rendering. **Use this
+  whenever you'd otherwise pipe through `jq`, `head`, `python -c`, or
+  similar shell tools to extract a few fields.** Stable field set per
+  resource (identifier, title, state, assignee, project, labels, URL for
+  issues; analogous fields for projects, comments, cycles, milestones,
+  teams, labels, users, documents, templates, attachments, releases, and
+  cross-resource search results).
+
+> **Working with an LLM / Claude Code?** Default every read/list call to
+> `--format summary` unless you specifically need the JSON envelope.
+> A 12-line summary table is dramatically cheaper in tokens than a 500-line
+> JSON dump and contains the same information humans actually use. The
+> bundled `claude-skills/linear-operations/SKILL.md` documents this rule.
+
+```bash
+el-linear issues read DEV-123 --format summary
+# DEV-123  Fix login flicker on Safari 17
+# State:    In Progress
+# Assignee: Alice
+# Project:  Auth Refactor
+# Labels:   Feature, tool
+# URL:      https://linear.app/acme/issue/DEV-123/...
+#
+#   Login button briefly disappears when the form first loads.
+#   Repro on Safari 17 / iOS 17. Chrome / Firefox unaffected.
+#   ... (truncated; --format json for full body)
+
+el-linear issues search "auth" --format summary
+# ID        TITLE                                                    STATE        ASSIGNEE
+# ---------------------------------------------------------------------------------------
+# DEV-100   Migrate auth middleware to new session store             In Progress  Alice
+# DEV-104   Auth callback returns 502 under load                     Todo         Bob
+#
+# 2 issues
+
+el-linear projects list --format summary
+# NAME                       STATE      PROGRESS  LEAD
+# -------------------------------------------------------
+# Auth Refactor              started    65%       Alice
+# Pricing v2                 backlog    0%        —
+#
+# 2 projects
+
+el-linear templates list --format summary
+# NAME              TYPE      TEAM  ID
+# ------------------------------------------------------------------
+# Bug report        issue     PYT   cf45b82e-0c71-4d24-be70-d4ecf915
+# Tech Planning     document  —     d4bcb82e-5ee4-49d3-b057-40f4a2e2
+#
+# 2 templates
+```
+
+Existing `issues list`, `issues search`, and `projects list` commands
+continue to accept their per-command formats too: `table`, `md`,
+`markdown`, `csv` — those go to the per-command rendering path. The
+global `summary` value works on every read/list command.
+
+`--format summary` does not compose with `--jq` (jq is JSON-only) or
+`--fields` (fields filter the JSON shape, not the rendered text). Use
+`--raw` together with `--format summary` to render a list envelope as a
+bare item-list rather than an envelope.
 
 ## Wrapping Linear references in arbitrary text
 

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

@@ -12,6 +12,61 @@ This skill covers **mandatory processes and non-obvious rules** — everything t
 
 > **Team-specific overrides.** Many teams keep their own issue-creation guide, label taxonomy, or member alias map. If your project has a `CLAUDE.md` or sibling skill that supplements this one, treat its rules as authoritative on top of these defaults.
 
+## Output formats — use `--format summary` for terminals and agents
+
+`el-linear` defaults to a structured JSON envelope. **For human-readable or chat-bound output, always pass `--format summary`.** Do not pipe el-linear through `python -c "json.load(...)"` or `jq` to pull out title / state / assignee — that is exactly what `--format summary` is for, and it produces a stable rendering across releases.
+
+```bash
+el-linear issues read DEV-123 --format summary
+# DEV-123  Fix login flicker on Safari 17
+# State:    In Progress
+# Assignee: Alice
+# Project:  Auth Refactor
+# Labels:   Feature, tool
+# URL:      https://linear.app/acme/issue/DEV-123/...
+
+el-linear issues search "auth" --format summary
+# ID        TITLE                                                    STATE        ASSIGNEE
+# ---------------------------------------------------------------------------------------
+# DEV-100   Migrate auth middleware to new session store             In Progress  Alice
+# DEV-104   Auth callback returns 502 under load                     Todo         Bob
+#
+# 2 issues
+```
+
+Use `--format json` (the default — pass nothing) **only** when you genuinely need the full envelope: writing scripts that parse the response, mutating with `--jq`, or chaining into another tool that expects structured data. Default to summary; reach for JSON when the task warrants it.
+
+### Anti-patterns to avoid
+
+If you find yourself writing any of these, you are reaching for the wrong tool:
+
+```bash
+# ❌ Don't do this — pipe through python to extract a few fields
+el-linear issues search "..." --limit 10 2>&1 | python3 -c "import json,sys; d=json.load(sys.stdin); ..."
+
+# ❌ Don't do this either — head the JSON to make it manageable
+el-linear projects list --limit 50 2>&1 | head -100
+
+# ❌ Don't reach for jq just to print title + state
+el-linear issues read DEV-123 --jq '.title + " " + .state.name' 2>&1
+
+# ✅ Just use --format summary
+el-linear issues search "..." --limit 10 --format summary 2>&1
+el-linear projects list --limit 50 --format summary 2>&1
+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.
+
+### Coverage
+
+`--format summary` is implemented for:
+
+- **Single resources:** `issues read`, `projects read`, `cycles read`, `project-milestones read`, `documents read`, `templates read`, releases (`graphql` query results), `users read`
+- **Lists:** `issues list`, `issues search`, `projects list`, `comments list`, `cycles list`, `project-milestones list`, `labels list`, `teams list`, `users list`, `documents list`, `templates list`, `attachments list`, `releases list`, and the cross-resource `search` command
+
+Commands without a dedicated formatter (e.g. `config show`, custom `graphql` queries) fall back to a generic key/value rendering of their JSON payload.
+
 ---
 
 ## Intent-Driven Issue Writing

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

@@ -0,0 +1,21 @@
+/**
+ * Optional local OAuth app defaults.
+ *
+ * This deliberately lives outside the packaged/default config. Teams can
+ * 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 {
+    clientId: string;
+    redirectPort: number;
+    scopes: OAuthScope[];
+    /**
+     * Optional human-facing pointer such as `op://vault/item/client_id`.
+     * The CLI does not execute password-manager commands from this value.
+     */
+    passwordManagerPath?: string;
+    sourcePath: string;
+}
+export declare function readTeamOAuthConfig(env?: NodeJS.ProcessEnv): Promise<TeamOAuthConfig | null>;

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

@@ -0,0 +1,82 @@
+/**
+ * Optional local OAuth app defaults.
+ *
+ * This deliberately lives outside the packaged/default config. Teams can
+ * 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 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";
+export async function readTeamOAuthConfig(env = process.env) {
+    const envPath = env[TEAM_OAUTH_CONFIG_ENV]?.trim();
+    const sourcePath = envPath || TEAM_OAUTH_CONFIG_PATH;
+    let raw;
+    try {
+        raw = await fs.readFile(sourcePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT" && !envPath) {
+            return null;
+        }
+        if (err.code === "ENOENT") {
+            throw new Error(`${TEAM_OAUTH_CONFIG_ENV} points to ${sourcePath}, but that file does not exist.`);
+        }
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to parse ${sourcePath}: ${message}`);
+    }
+    const linearOAuth = parsed.linearOAuth;
+    if (!linearOAuth || typeof linearOAuth !== "object") {
+        throw new Error(`${sourcePath} must contain a linearOAuth object with a clientId.`);
+    }
+    const clientId = typeof linearOAuth.clientId === "string" ? linearOAuth.clientId.trim() : "";
+    if (!clientId) {
+        throw new Error(`${sourcePath} linearOAuth.clientId must be a string.`);
+    }
+    const redirectPort = parseRedirectPort(linearOAuth.redirectPort, sourcePath);
+    const scopes = parseScopes(linearOAuth.scopes, sourcePath);
+    const passwordManagerPath = parsePasswordManagerPath(linearOAuth.passwordManagerPath, sourcePath);
+    return {
+        clientId,
+        redirectPort,
+        scopes,
+        passwordManagerPath,
+        sourcePath,
+    };
+}
+function parseRedirectPort(value, sourcePath) {
+    if (value === undefined)
+        return 8765;
+    if (typeof value !== "number" ||
+        !Number.isInteger(value) ||
+        value < 1024 ||
+        value > 65535) {
+        throw new Error(`${sourcePath} linearOAuth.redirectPort must be an integer between 1024 and 65535.`);
+    }
+    return value;
+}
+function parseScopes(value, sourcePath) {
+    if (value === undefined)
+        return [...DEFAULT_SCOPES];
+    if (!Array.isArray(value) || !value.every((s) => typeof s === "string")) {
+        throw new Error(`${sourcePath} linearOAuth.scopes must be a string array.`);
+    }
+    return validateScopes(value);
+}
+function parsePasswordManagerPath(value, sourcePath) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string") {
+        throw new Error(`${sourcePath} linearOAuth.passwordManagerPath must be a string when set.`);
+    }
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}

package/dist/auth/oauth-callback.js

@@ -30,20 +30,27 @@ const SUCCESS_HTML = `<!doctype html>
 <p>You can close this tab and return to your terminal.</p>
 </body>
 </html>`;
-function errorHtml(message) {
-    const safe = message.replace(/[<>&]/g, "");
-    return `<!doctype html>
+// Fixed error page — never interpolates attacker-controlled prose.
+//
+// Pre-fix: the upstream `error_description` from the redirect URL was
+// embedded into the HTML response (with `<>&` stripped). An attacker
+// who knew the local listener port could fire
+// `http://localhost:<port>/oauth/callback?error=phish&error_description=Your+account+is+compromised…`
+// and have arbitrary phishing prose render in the user's browser
+// before the legitimate redirect arrived. Now we render a fixed
+// string and log the upstream detail to the terminal where the user
+// can compare it to expected output.
+const ERROR_HTML = `<!doctype html>
 <html lang="en">
 <head><meta charset="utf-8"><title>el-linear · authorization error</title>
 <style>body{font-family:system-ui,sans-serif;max-width:560px;margin:64px auto;padding:0 16px;color:#1a1a1a}h1{font-size:18px;margin:0 0 12px}p{margin:8px 0}.bad{color:#a30000}code{background:#f4f4f4;padding:2px 4px;border-radius:3px}</style>
 </head>
 <body>
 <h1 class="bad">el-linear · authorization error</h1>
-<p>${safe}</p>
+<p>Authorization failed. Return to your terminal — the CLI has the details.</p>
 <p>You can close this tab. Re-run <code>el-linear init oauth</code> to retry.</p>
 </body>
 </html>`;
-}
 /**
  * Spin up a one-shot HTTP server on `127.0.0.1:<port>`, accept the OAuth
  * callback, validate state, and resolve with `{code, state}`.
@@ -95,7 +102,7 @@ export async function runLocalhostCallback(options, serverFactory = () => create
                     const message = err instanceof Error ? err.message : String(err);
                     res.statusCode = 400;
                     res.setHeader("content-type", "text/html; charset=utf-8");
-                    res.end(errorHtml(message));
+                    res.end(ERROR_HTML);
                     settle(() => reject(new Error(message)));
                     return;
                 }
@@ -103,7 +110,7 @@ export async function runLocalhostCallback(options, serverFactory = () => create
                     const message = "State mismatch — the OAuth callback's `state` parameter doesn't match what we sent. This could indicate a CSRF attempt; aborting.";
                     res.statusCode = 400;
                     res.setHeader("content-type", "text/html; charset=utf-8");
-                    res.end(errorHtml(message));
+                    res.end(ERROR_HTML);
                     settle(() => reject(new Error(message)));
                     return;
                 }

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

@@ -1 +1,23 @@
 export declare function atomicWrite(targetPath: string, data: string | Uint8Array, mode?: number): Promise<void>;
+export 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. */
+    maxWaitMs?: number;
+    /** Poll interval while waiting. Default 100ms. */
+    pollMs?: number;
+}
+/**
+ * Run `fn` while holding an exclusive file lock at `<targetPath>.lock`.
+ *
+ * Implementation: `fs.open(..., "wx")` is the POSIX `O_EXCL` create — it
+ * fails atomically if the lockfile already exists. On success we own the
+ * lock; we delete the file in `finally` so a synchronous throw still
+ * releases. A crashed process leaves the lockfile behind; the next caller
+ * detects staleness via `mtime` and steals the lock.
+ *
+ * Limitations: this is a single-machine lock. NFS-style multi-machine
+ * coordination is out of scope (and the OAuth state is per-machine
+ * anyway).
+ */
+export declare function withFileLock<T>(targetPath: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;

package/dist/auth/oauth-fs.js

@@ -1,14 +1,20 @@
 /**
- * Internal: atomic write helper used by `oauth-storage.ts`.
+ * Internal: filesystem helpers for the auth module.
  *
  * The wizard already has an `atomicWrite` in `commands/init/shared.ts`, but
  * importing wizard internals from non-wizard code creates a cycle (the
  * wizard depends on `auth/`, and `auth/` would depend back on the wizard).
- * Duplicating the 12-line helper here keeps the dependency graph clean.
+ * Duplicating the helpers here keeps the dependency graph clean.
  *
- * Behaviour matches `commands/init/shared.ts#atomicWrite`: write to a sibling
- * tmp file then `rename`. On POSIX same-filesystem, rename is atomic. The
- * tmp suffix uses crypto-random bytes so concurrent writers don't collide.
+ * `atomicWrite` matches `commands/init/shared.ts#atomicWrite`: write to a
+ * sibling tmp file then `rename`. On POSIX same-filesystem, rename is
+ * atomic. The tmp suffix uses crypto-random bytes so concurrent writers
+ * don't collide.
+ *
+ * `withFileLock` serialises a critical section using a sidecar `<path>.lock`
+ * file created with `O_EXCL`. Used by the OAuth refresh path so two
+ * concurrent CLI invocations can't both consume the same refresh token,
+ * which would invalidate it on Linear's side and brick the user's auth.
  */
 import { randomBytes } from "node:crypto";
 import fs from "node:fs/promises";
@@ -16,7 +22,7 @@ export async function atomicWrite(targetPath, data, mode = 0o644) {
     const tmpPath = `${targetPath}.tmp-${randomBytes(8).toString("hex")}`;
     try {
         await fs.writeFile(tmpPath, data, { encoding: "utf8", mode });
-        // fs.writeFile only honours `mode` when the file is newly created.
+        // fs.writeFile only honors `mode` when the file is newly created.
         // Tmp paths are always new, but be explicit to make this airtight if
         // the random suffix ever collides with a stale tmp.
         await fs.chmod(tmpPath, mode);
@@ -27,3 +33,68 @@ export async function atomicWrite(targetPath, data, mode = 0o644) {
         throw err;
     }
 }
+/**
+ * Run `fn` while holding an exclusive file lock at `<targetPath>.lock`.
+ *
+ * Implementation: `fs.open(..., "wx")` is the POSIX `O_EXCL` create — it
+ * fails atomically if the lockfile already exists. On success we own the
+ * lock; we delete the file in `finally` so a synchronous throw still
+ * releases. A crashed process leaves the lockfile behind; the next caller
+ * detects staleness via `mtime` and steals the lock.
+ *
+ * Limitations: this is a single-machine lock. NFS-style multi-machine
+ * coordination is out of scope (and the OAuth state is per-machine
+ * anyway).
+ */
+export async function withFileLock(targetPath, fn, options = {}) {
+    const staleAfterMs = options.staleAfterMs ?? 30_000;
+    const maxWaitMs = options.maxWaitMs ?? 30_000;
+    const pollMs = options.pollMs ?? 100;
+    const lockPath = `${targetPath}.lock`;
+    const start = Date.now();
+    while (true) {
+        try {
+            const handle = await fs.open(lockPath, "wx");
+            try {
+                await handle.writeFile(`${process.pid}\n${Date.now()}\n`);
+            }
+            finally {
+                await handle.close();
+            }
+            try {
+                return await fn();
+            }
+            finally {
+                await fs.unlink(lockPath).catch(() => { });
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST")
+                throw err;
+            // Lockfile already exists. Check whether it's stale (process died
+            // before releasing) and either steal it or wait.
+            let stolen = false;
+            try {
+                const stat = await fs.stat(lockPath);
+                if (Date.now() - stat.mtimeMs > staleAfterMs) {
+                    await fs.unlink(lockPath).catch(() => { });
+                    stolen = true;
+                }
+            }
+            catch {
+                // Lockfile was removed between the EEXIST and the stat. Race
+                // with the holder's normal release path — just retry.
+                stolen = true;
+            }
+            if (stolen)
+                continue;
+            if (Date.now() - start > maxWaitMs) {
+                throw new Error(`Timed out after ${maxWaitMs}ms waiting for ${lockPath}. ` +
+                    `Another el-linear process is holding the lock; if none is running, ` +
+                    `delete the file manually and retry.`);
+            }
+            await new Promise((r) => setTimeout(r, pollMs));
+        }
+    }
+}

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

@@ -18,6 +18,13 @@
 import { type CallbackParams } from "./oauth-client.js";
 export interface PromptForPastedCodeOptions {
     expectedState: string;
+    /**
+     * Allow the user to paste a bare authorization code without a
+     * surrounding URL. Defeats the OAuth `state` CSRF check (we can't
+     * verify state without the URL), so it's gated behind explicit
+     * opt-in. Default: false — paste the full callback URL.
+     */
+    unsafeBareCode?: boolean;
     /** Test seam — defaults to @inquirer/prompts `input`. */
     prompt?: (opts: {
         message: string;
@@ -25,14 +32,12 @@ export interface PromptForPastedCodeOptions {
     }) => Promise<string>;
 }
 /**
- * Ask the user to paste either:
- *   - The full callback URL (we extract code+state ourselves), OR
- *   - Just the `code` value (we accept the user's word on state).
+ * Ask the user to paste the full OAuth callback URL. We parse `code`
+ * and `state`, then verify `state` matches what we sent.
  *
- * For the URL form, state is validated against `expectedState`.
- *
- * Returns `{code, state}`. When the user pasted only a code, `state` is
- * the expected value (the user has implicitly trusted it; we have no
- * other check available).
+ * Bare `code` pastes (no URL) are rejected by default because we have
+ * no way to verify the `state` parameter — the entire CSRF protection
+ * collapses if we silently accept the expected state on the user's
+ * behalf. Opt in with `--unsafe-bare-code` (`unsafeBareCode: true`).
  */
 export declare function promptForPastedCode(options: PromptForPastedCodeOptions): Promise<CallbackParams>;

package/dist/auth/oauth-headless.js

@@ -18,20 +18,21 @@
 import { input } from "@inquirer/prompts";
 import { parseCallbackUrl } from "./oauth-client.js";
 /**
- * Ask the user to paste either:
- *   - The full callback URL (we extract code+state ourselves), OR
- *   - Just the `code` value (we accept the user's word on state).
+ * Ask the user to paste the full OAuth callback URL. We parse `code`
+ * and `state`, then verify `state` matches what we sent.
  *
- * For the URL form, state is validated against `expectedState`.
- *
- * Returns `{code, state}`. When the user pasted only a code, `state` is
- * the expected value (the user has implicitly trusted it; we have no
- * other check available).
+ * Bare `code` pastes (no URL) are rejected by default because we have
+ * no way to verify the `state` parameter — the entire CSRF protection
+ * collapses if we silently accept the expected state on the user's
+ * behalf. Opt in with `--unsafe-bare-code` (`unsafeBareCode: true`).
  */
 export async function promptForPastedCode(options) {
     const ask = options.prompt ?? ((o) => input(o));
+    const message = options.unsafeBareCode
+        ? "Paste the full callback URL (or just the `code` value, since --unsafe-bare-code was set):"
+        : "Paste the full callback URL (it includes both `code` and `state`):";
     const raw = (await ask({
-        message: "Paste the full callback URL (or just the `code` value):",
+        message,
         validate: (value) => value.trim().length > 0 || "Cannot be empty",
     })).trim();
     if (raw.startsWith("http://") || raw.startsWith("https://")) {
@@ -41,8 +42,14 @@ export async function promptForPastedCode(options) {
         }
         return parsed;
     }
-    // Bare code path. Reject anything that looks like it has a query
-    // string but isn't a URL (the user partially copied something).
+    // Bare-code pastes are opt-in. Without `unsafeBareCode`, refuse to
+    // silently fabricate `state` and bypass CSRF.
+    if (!options.unsafeBareCode) {
+        throw new Error("Paste the FULL callback URL — bare `code` pastes are disabled because they bypass the OAuth `state` CSRF check. " +
+            "Re-run with `--unsafe-bare-code` only if you understand and accept the risk.");
+    }
+    // Reject anything that looks like a query fragment but isn't a URL
+    // (the user partially copied something).
     if (raw.includes("=") || raw.includes("?")) {
         throw new Error("Pasted value looks malformed. Paste either the full callback URL or just the `code` value (alphanumeric + dashes).");
     }

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

@@ -29,20 +29,28 @@ export declare function oauthStatePath(): string;
  * Returns `null` (not throw) on JSON parse errors so callers can fall back
  * to personal-token auth without spamming users with repair instructions —
  * the `init oauth` command is responsible for repair.
+ *
+ * Pass an explicit `targetPath` to bind to a specific profile's
+ * `oauth.json`. Useful for read-modify-write sequences that snapshot
+ * the path once at the top so a profile switch mid-sequence can't
+ * cause cross-profile contamination. ALL-935.
  */
-export declare function readOAuthState(): Promise<OAuthState | null>;
+export declare function readOAuthState(targetPath?: string): Promise<OAuthState | null>;
 /**
  * Write the active profile's OAuth state atomically with mode 0600.
  *
  * IMPORTANT: uses the same write-tmp + rename pattern as `writeToken` so a
  * pre-existing 0644 file gets its mode reset. Tokens leaking via group/other
  * read is the failure mode we want to make impossible.
+ *
+ * Pass an explicit `targetPath` to bind to a specific profile (see
+ * `readOAuthState`).
  */
-export declare function writeOAuthState(state: OAuthState): Promise<void>;
+export declare function writeOAuthState(state: OAuthState, targetPath?: string): Promise<void>;
 /**
  * Delete the active profile's OAuth state. No-op if the file is already gone.
  */
-export declare function clearOAuthState(): Promise<void>;
+export declare function clearOAuthState(targetPath?: string): Promise<void>;
 /**
  * Return `true` when the access token is still valid for at least
  * `skewMs` milliseconds. Default 60s skew protects against clock drift +

package/dist/auth/oauth-storage.js

@@ -30,10 +30,15 @@ export function oauthStatePath() {
  * Returns `null` (not throw) on JSON parse errors so callers can fall back
  * to personal-token auth without spamming users with repair instructions —
  * the `init oauth` command is responsible for repair.
+ *
+ * Pass an explicit `targetPath` to bind to a specific profile's
+ * `oauth.json`. Useful for read-modify-write sequences that snapshot
+ * the path once at the top so a profile switch mid-sequence can't
+ * cause cross-profile contamination. ALL-935.
  */
-export async function readOAuthState() {
+export async function readOAuthState(targetPath = oauthStatePath()) {
     try {
-        const raw = await fs.readFile(oauthStatePath(), "utf8");
+        const raw = await fs.readFile(targetPath, "utf8");
         const parsed = JSON.parse(raw);
         if (parsed?.v !== OAUTH_STATE_VERSION)
             return null;
@@ -56,21 +61,23 @@ export async function readOAuthState() {
  * IMPORTANT: uses the same write-tmp + rename pattern as `writeToken` so a
  * pre-existing 0644 file gets its mode reset. Tokens leaking via group/other
  * read is the failure mode we want to make impossible.
+ *
+ * Pass an explicit `targetPath` to bind to a specific profile (see
+ * `readOAuthState`).
  */
-export async function writeOAuthState(state) {
-    const target = oauthStatePath();
+export async function writeOAuthState(state, targetPath = oauthStatePath()) {
     // Ensure both the legacy CONFIG_DIR (where active-profile + profiles/
     // live) and the active profile's directory exist before writing.
     await fs.mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
-    await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
-    await atomicWrite(target, `${JSON.stringify(state, null, 2)}\n`, 0o600);
+    await fs.mkdir(path.dirname(targetPath), { recursive: true, mode: 0o700 });
+    await atomicWrite(targetPath, `${JSON.stringify(state, null, 2)}\n`, 0o600);
 }
 /**
  * Delete the active profile's OAuth state. No-op if the file is already gone.
  */
-export async function clearOAuthState() {
+export async function clearOAuthState(targetPath = oauthStatePath()) {
     try {
-        await fs.unlink(oauthStatePath());
+        await fs.unlink(targetPath);
     }
     catch (err) {
         if (err.code !== "ENOENT")

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

@@ -44,5 +44,14 @@ export declare function getActiveAuth(options?: GetActiveAuthOptions): Promise<A
  *
  * On refresh failure, throws an actionable error pointing at
  * `el-linear init oauth`.
+ *
+ * **Concurrency.** When a refresh is needed, this acquires an exclusive
+ * file lock on the oauth.json sidecar before reading-refreshing-writing.
+ * Two parallel CLI invocations would otherwise both call `refreshTokens`
+ * with the same refresh token; Linear's server invalidates the loser's
+ * stored token and the next refresh permanently fails. The lock
+ * serialises them — the second process re-reads the freshly-written
+ * state inside the lock and uses the winner's tokens instead of issuing
+ * a second refresh.
  */
 export declare function ensureFreshAccessToken(state: OAuthState, options?: GetActiveAuthOptions): Promise<OAuthState>;