@enrichlayer/el-linear 1.7.0 → 1.9.0

package/README.md

@@ -302,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-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>;

package/dist/auth/token-resolver.js

@@ -16,7 +16,8 @@
  *   - oauth:     `Authorization: Bearer <token>`
  */
 import { getApiToken } from "../utils/auth.js";
-import { isAccessTokenFresh, readOAuthState, writeOAuthState, } from "./oauth-storage.js";
+import { withFileLock } from "./oauth-fs.js";
+import { oauthStatePath, readOAuthState, writeOAuthState, } from "./oauth-storage.js";
 import { refreshTokens, } from "./oauth-token.js";
 /**
  * Resolve the credential for this invocation.
@@ -52,44 +53,63 @@ export async function getActiveAuth(options = {}) {
  *
  * 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 async function ensureFreshAccessToken(state, options = {}) {
     const now = options.now ?? Date.now;
-    if (isAccessTokenFresh(state, /* skewMs */ 60_000)) {
-        // `isAccessTokenFresh` reads `Date.now()` internally; for the
-        // purpose of the test seam we re-check against the injected clock.
-        if (now() + 60_000 < state.expiresAt) {
-            return state;
-        }
-    }
-    if (!state.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: state.clientId,
-            clientSecret: state.clientSecret,
-            refreshToken: state.refreshToken,
-        }, options.fetchImpl, now);
-    }
-    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.`);
+    // Fast path: token is fresh; no lock, no refresh.
+    if (now() + 60_000 < state.expiresAt) {
+        return state;
     }
-    const next = {
-        ...state,
-        accessToken: refreshed.accessToken,
-        // Preserve the previous refresh token if the server didn't rotate
-        // (some OAuth servers only return a new refresh_token periodically).
-        refreshToken: refreshed.refreshToken ?? state.refreshToken,
-        tokenType: refreshed.tokenType,
-        // Use the freshly-returned scopes only if non-empty; otherwise keep
-        // what we had, since some token endpoints omit `scope` on refresh.
-        scopes: refreshed.scopes.length > 0 ? refreshed.scopes : state.scopes,
-        expiresAt: refreshed.expiresAt,
-        obtainedAt: now(),
-    };
-    await writeOAuthState(next);
-    return next;
+    // Snapshot the target path ONCE so a profile switch between the
+    // lock acquisition and the write inside the closure can't cause
+    // cross-profile contamination. The lock + read + write all bind
+    // to this path. ALL-935 deferred fix.
+    const targetPath = oauthStatePath();
+    return withFileLock(targetPath, async () => {
+        // 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) {
+            return current;
+        }
+        if (!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);
+        }
+        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.`);
+        }
+        const next = {
+            ...current,
+            accessToken: refreshed.accessToken,
+            // Preserve the previous refresh token if the server didn't rotate
+            // (some OAuth servers only return a new refresh_token periodically).
+            refreshToken: refreshed.refreshToken ?? current.refreshToken,
+            tokenType: refreshed.tokenType,
+            // Use the freshly-returned scopes only if non-empty; otherwise
+            // keep what we had — some token endpoints omit `scope` on refresh.
+            scopes: refreshed.scopes.length > 0 ? refreshed.scopes : current.scopes,
+            expiresAt: refreshed.expiresAt,
+            obtainedAt: now(),
+        };
+        await writeOAuthState(next, targetPath);
+        return next;
+    });
 }

package/dist/commands/init/index.js

@@ -63,6 +63,7 @@ export function setupInitCommands(program) {
         .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))
+        .option("--unsafe-bare-code", "allow pasting a bare authorization code in the headless flow (skips the OAuth `state` CSRF check; opt-in only)")
         .action(withCleanExit(async (options) => {
         printStep("oauth", "Linear OAuth (PKCE)");
         if (options.revoke) {
@@ -75,6 +76,7 @@ export function setupInitCommands(program) {
             // commander's `--no-browser` produces `browser: false`.
             noBrowser: options.browser === false,
             port: options.port,
+            unsafeBareCode: options.unsafeBareCode === true,
         });
     }));
     init

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

@@ -39,6 +39,12 @@ export interface OAuthStepOptions {
     noBrowser?: boolean;
     /** Override the localhost port. Default 8765. */
     port?: number;
+    /**
+     * Allow pasting a bare authorization code (no surrounding URL) in
+     * the headless flow. Bypasses the OAuth `state` CSRF check, so
+     * opt-in only — see `oauth-headless.ts` for the rationale.
+     */
+    unsafeBareCode?: boolean;
     /** Test seam for the OAuth token endpoint. */
     fetchImpl?: FetchLike;
     /**