@enrichlayer/el-linear 1.44.2 → 1.46.0

package/dist/config/label-advisor.d.ts

@@ -0,0 +1,53 @@
+import type { ElLinearConfig } from "./config.js";
+export interface LabelAdvisorInput {
+    team: string | null;
+    project: string | null;
+    title: string | null;
+    description: string | null;
+    labels: string[];
+    state: string | null;
+}
+/**
+ * Receipt policy fields an advisor may return with a consent label
+ * (DEV-10455). el-linear never guesses these: `repo` is the repository the
+ * organization's intake policy maps this issue to, and `reason` is why that
+ * policy consents to unattended work. el-linear adds only what it knows
+ * itself (the new issue's identifier and the acting Linear user) and writes
+ * the receipt after the issue exists. See `consent-receipt.ts`.
+ */
+export interface LabelAdvisorReceipt {
+    repo: string;
+    reason: string;
+}
+export type LabelAdvisorResult = {
+    ok: true;
+    labels: string[];
+    reason: string | null;
+    receipt: LabelAdvisorReceipt | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The configured advisor argv, or `null` when the hook is off. Env wins over
+ * config so one invocation can point elsewhere or disable it without editing
+ * files.
+ */
+export declare function labelAdvisorCommand(config: Pick<ElLinearConfig, "labelAdvisor">, env?: NodeJS.ProcessEnv): string[] | null;
+/**
+ * Parse what the advisor printed. Returns an error string for anything that is
+ * not exactly a well-formed answer — a malformed answer is a failure, and a
+ * failure adds no labels. Partial acceptance (keep the valid elements, drop the
+ * rest) is deliberately not offered: an advisor emitting garbage is broken, and
+ * trusting half of its output is how a wrong label slips in.
+ */
+export declare function parseLabelAdvisorOutput(stdout: string): LabelAdvisorResult;
+/**
+ * Run the configured advisor. Returns `null` when no advisor is configured,
+ * otherwise the parsed advice or a failure. Never throws.
+ *
+ * Synchronous for the same reason as the identity resolver: it sits on the
+ * critical path of a short-lived CLI, and a single failure site is easier to
+ * reason about than a promise race.
+ */
+export declare function runLabelAdvisor(input: LabelAdvisorInput, config: Pick<ElLinearConfig, "labelAdvisor">, env?: NodeJS.ProcessEnv): LabelAdvisorResult | null;

package/dist/config/label-advisor.js

@@ -0,0 +1,245 @@
+import { spawnSync } from "node:child_process";
+/**
+ * Optional **label advisor hook** (DEV-10372).
+ *
+ * An organization may have a rubric that knows which labels a new issue should
+ * carry — for example "this Tools issue is small and well specified, so it
+ * belongs in the unattended-automation lane". el-linear can consult it on
+ * `issues create`, but it must never learn *what* the rubric is or how to run
+ * it. So the hook is a **command**, modelled on the identity resolver
+ * (DEV-5628, `identity-resolver.ts`):
+ *
+ *   "labelAdvisor": { "command": ["my-rubric", "--advise"] }
+ *
+ * Contract:
+ *
+ *   - stdin: one JSON object describing the proposed issue —
+ *     `{team, project, title, description, labels, state}`.
+ *   - stdout: JSON. Either a bare array of label names (`["bot"]`) or an
+ *     object `{"labels": ["bot"], "reason": "…"}`; one level of `{data: …}`
+ *     envelope is unwrapped (the el-* CLI shape). `{"labels": []}` means
+ *     "nothing to add". With a consent label (see `consent-receipt.ts`) the
+ *     object may also carry `"receipt": {"repo": "…", "reason": "…"}`; then
+ *     el-linear applies the consent label after create together with an
+ *     `el-intake-decision:v1` receipt naming the new issue.
+ *   - exit 0 on success.
+ *
+ * **Fail-closed on labels.** A label may carry meaning — in some workspaces a
+ * label is consent for unattended work — so a broken advisor must never add
+ * one. Non-zero exit, timeout, missing binary, unparseable or malformed output
+ * all return a failure; the caller warns and creates the issue with exactly
+ * the labels the author asked for. The hook never throws.
+ *
+ * The issue text is untrusted input (agents create issues from arbitrary
+ * prose), so it travels on stdin, never in argv, and the command runs with
+ * `shell: false`.
+ */
+/** Env override — a whitespace-separated command; `""` is an explicit OFF. */
+const ADVISOR_ENV = "EL_LINEAR_LABEL_ADVISOR";
+/** An advisor that hasn't answered in this long is not going to. */
+const DEFAULT_TIMEOUT_MS = 5000;
+/** Advice for more labels than this is a confused advisor, not a rubric. */
+const MAX_LABELS = 10;
+const MAX_LABEL_LENGTH = 80;
+const MAX_REASON_LENGTH = 300;
+const MAX_RECEIPT_REPO_LENGTH = 200;
+const MAX_RECEIPT_REASON_LENGTH = 500;
+/** True when `text` has no ASCII control character (U+0000–U+001F, U+007F). */
+function isSafeText(text) {
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f)
+            return false;
+    }
+    return text.length > 0;
+}
+/**
+ * The configured advisor argv, or `null` when the hook is off. Env wins over
+ * config so one invocation can point elsewhere or disable it without editing
+ * files.
+ */
+export function labelAdvisorCommand(config, env = process.env) {
+    const fromEnv = env[ADVISOR_ENV];
+    if (fromEnv !== undefined) {
+        const argv = fromEnv.trim().split(/\s+/).filter(Boolean);
+        return argv.length > 0 ? argv : null;
+    }
+    const configured = config.labelAdvisor?.command;
+    if (!Array.isArray(configured) || configured.length === 0) {
+        return null;
+    }
+    return configured;
+}
+/**
+ * Resolve the effective timeout. Node treats `timeout <= 0` as *no timeout*,
+ * which would turn a hung advisor into a hung CLI — so non-positive values
+ * fall back to the default, exactly like the identity resolver.
+ */
+function resolveTimeoutMs(config) {
+    const configured = config.labelAdvisor?.timeoutMs;
+    return typeof configured === "number" && configured > 0
+        ? configured
+        : DEFAULT_TIMEOUT_MS;
+}
+/** The advisor classifies issue text; it never needs Linear's token. */
+function advisorEnv(env) {
+    const { LINEAR_API_TOKEN: _dropped, ...rest } = env;
+    return rest;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Parse what the advisor printed. Returns an error string for anything that is
+ * not exactly a well-formed answer — a malformed answer is a failure, and a
+ * failure adds no labels. Partial acceptance (keep the valid elements, drop the
+ * rest) is deliberately not offered: an advisor emitting garbage is broken, and
+ * trusting half of its output is how a wrong label slips in.
+ */
+export function parseLabelAdvisorOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        return { ok: false, error: "advisor printed nothing (expected JSON)" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return { ok: false, error: "advisor output is not valid JSON" };
+    }
+    if (isRecord(parsed) && isRecord(parsed.data)) {
+        parsed = parsed.data;
+    }
+    let rawLabels;
+    let rawReason = null;
+    let rawReceipt = null;
+    if (Array.isArray(parsed)) {
+        rawLabels = parsed;
+    }
+    else if (isRecord(parsed)) {
+        rawLabels = parsed.labels;
+        rawReason = parsed.reason ?? null;
+        rawReceipt = parsed.receipt ?? null;
+    }
+    else {
+        return {
+            ok: false,
+            error: "advisor output must be a label array or an object",
+        };
+    }
+    if (!Array.isArray(rawLabels)) {
+        return { ok: false, error: 'advisor output has no "labels" array' };
+    }
+    if (rawLabels.length > MAX_LABELS) {
+        return {
+            ok: false,
+            error: `advisor returned ${rawLabels.length} labels (limit ${MAX_LABELS})`,
+        };
+    }
+    const labels = [];
+    for (const label of rawLabels) {
+        if (typeof label !== "string" ||
+            label.trim().length === 0 ||
+            label.length > MAX_LABEL_LENGTH ||
+            !isSafeText(label) ||
+            label.includes(",")) {
+            return {
+                ok: false,
+                error: "advisor returned a label that is not a plain label name",
+            };
+        }
+        const name = label.trim();
+        if (!labels.some((seen) => seen.toLowerCase() === name.toLowerCase())) {
+            labels.push(name);
+        }
+    }
+    if (rawReason !== null && typeof rawReason !== "string") {
+        return { ok: false, error: "advisor reason must be a string" };
+    }
+    const reason = typeof rawReason === "string" && rawReason.trim()
+        ? rawReason.replace(/\s+/g, " ").trim().slice(0, MAX_REASON_LENGTH)
+        : null;
+    const receipt = parseReceiptFields(rawReceipt);
+    if (typeof receipt === "string") {
+        return { ok: false, error: receipt };
+    }
+    return { ok: true, labels, reason, receipt };
+}
+/**
+ * Validate the optional `receipt` object. A malformed one fails the whole
+ * answer (returned as an error string): a receipt is consent, so half of one
+ * is never used.
+ */
+function parseReceiptFields(raw) {
+    if (raw === null) {
+        return null;
+    }
+    if (!isRecord(raw)) {
+        return "advisor receipt must be an object";
+    }
+    const { repo, reason } = raw;
+    if (typeof repo !== "string" ||
+        repo.trim().length === 0 ||
+        repo.length > MAX_RECEIPT_REPO_LENGTH ||
+        !isSafeText(repo)) {
+        return "advisor receipt.repo must be a non-empty plain string";
+    }
+    if (typeof reason !== "string" ||
+        reason.trim().length === 0 ||
+        reason.length > MAX_RECEIPT_REASON_LENGTH ||
+        !isSafeText(reason)) {
+        return `advisor receipt.reason must be a non-empty plain string of at most ${MAX_RECEIPT_REASON_LENGTH} characters`;
+    }
+    return { repo: repo.trim(), reason: reason.trim() };
+}
+/**
+ * Run the configured advisor. Returns `null` when no advisor is configured,
+ * otherwise the parsed advice or a failure. Never throws.
+ *
+ * Synchronous for the same reason as the identity resolver: it sits on the
+ * critical path of a short-lived CLI, and a single failure site is easier to
+ * reason about than a promise race.
+ */
+export function runLabelAdvisor(input, config, env = process.env) {
+    const argv = labelAdvisorCommand(config, env);
+    if (!argv) {
+        return null;
+    }
+    const [command, ...args] = argv;
+    if (!command) {
+        return null;
+    }
+    try {
+        const result = spawnSync(command, args, {
+            encoding: "utf8",
+            input: JSON.stringify(input),
+            timeout: resolveTimeoutMs(config),
+            // A trapped SIGTERM would let a broken advisor wedge the CLI past
+            // its time budget; see the identical note in identity-resolver.ts.
+            killSignal: "SIGKILL",
+            shell: false,
+            stdio: ["pipe", "pipe", "pipe"],
+            env: advisorEnv(env),
+        });
+        // Check `error` before `status`: a timeout that leaves a grandchild
+        // holding the pipe reports ETIMEDOUT with status 0 (identity-resolver.ts).
+        if (result.error) {
+            return { ok: false, error: `${command}: ${result.error.message}` };
+        }
+        if (result.status !== 0) {
+            const stderr = (result.stderr ?? "").trim().split("\n")[0] ?? "";
+            return {
+                ok: false,
+                error: `${command} exited ${result.status ?? `on ${result.signal}`}${stderr ? `: ${stderr}` : ""}`,
+            };
+        }
+        return parseLabelAdvisorOutput(result.stdout ?? "");
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}

package/dist/queries/catalog-types.d.ts

@@ -0,0 +1,129 @@
+export interface CatalogTeamRef {
+    id: string;
+    key: string;
+    name: string;
+}
+export interface CatalogProjectNode {
+    id: string;
+    name: string;
+    description: string | null;
+    state: string;
+    progress: number;
+    targetDate: string | null;
+    createdAt: string;
+    updatedAt: string;
+    lead: {
+        id: string;
+        name: string;
+    } | null;
+    teams: {
+        nodes: CatalogTeamRef[];
+    };
+}
+export interface CatalogPageInfo {
+    hasNextPage: boolean;
+    endCursor: string | null;
+}
+export interface ProjectCatalogConnection {
+    nodes: CatalogProjectNode[];
+    pageInfo: CatalogPageInfo;
+}
+export interface GetProjectsCatalogResponse {
+    projects: ProjectCatalogConnection | null;
+    team: {
+        projects: ProjectCatalogConnection;
+    } | null;
+}
+export interface CatalogLabelNode {
+    id: string;
+    name: string;
+    color: string;
+    isGroup: boolean;
+    parent: {
+        id: string;
+        name: string;
+    } | null;
+    team: CatalogTeamRef | null;
+}
+export interface GetLabelsCatalogResponse {
+    issueLabels: {
+        nodes: CatalogLabelNode[];
+    };
+}
+export interface CatalogCycleNode {
+    id: string;
+    name: string | null;
+    number: number;
+    startsAt: string | null;
+    endsAt: string | null;
+    isActive: boolean;
+    isPrevious: boolean;
+    isNext: boolean;
+    progress: number;
+    issueCountHistory: number[] | null;
+    team: CatalogTeamRef | null;
+}
+export interface GetCyclesCatalogResponse {
+    cycles: {
+        nodes: CatalogCycleNode[];
+    };
+}
+export interface CatalogIssueNode {
+    id: string;
+    identifier: string;
+    url: string;
+    title: string;
+    description: string | null;
+    priority: number;
+    estimate: number | null;
+    createdAt: string;
+    updatedAt: string;
+    state: {
+        id: string;
+        name: string;
+    } | null;
+    assignee: {
+        id: string;
+        name: string;
+    } | null;
+    team: CatalogTeamRef | null;
+    project: {
+        id: string;
+        name: string;
+    } | null;
+    labels: {
+        nodes: Array<{
+            id: string;
+            name: string;
+        }>;
+    };
+}
+export interface GetCycleDetailResponse {
+    cycle: (CatalogCycleNode & {
+        issues: {
+            nodes: CatalogIssueNode[];
+        };
+    }) | null;
+}
+export interface ResolveProjectCatalogResponse {
+    projects: {
+        nodes: Array<{
+            id: string;
+            name: string;
+            teams: {
+                nodes: CatalogTeamRef[];
+            };
+        }>;
+    } | null;
+    team: {
+        projects: {
+            nodes: Array<{
+                id: string;
+                name: string;
+                teams: {
+                    nodes: CatalogTeamRef[];
+                };
+            }>;
+        };
+    } | null;
+}

package/dist/queries/catalog-types.js

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

package/dist/queries/catalog.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Fetch project summaries, embedded teams, and lead in one paginated request.
+ * The conditional team branch replaces SDK relation follow-ups and keeps both
+ * request count and GraphQL complexity visible at one catalog boundary.
+ */
+export declare const GET_PROJECTS_CATALOG_QUERY = "\n  query GetProjectsCatalog(\n    $filter: ProjectFilter\n\t\t$teamId: String!\n\t\t$teamScoped: Boolean!\n    $first: Int!\n    $after: String\n  ) {\n    projects(filter: $filter, first: $first, after: $after, orderBy: updatedAt, includeArchived: false) @skip(if: $teamScoped) {\n      nodes { \n  id\n  name\n  description\n  state\n  progress\n  targetDate\n  createdAt\n  updatedAt\n  lead { id name }\n  teams { nodes { id key name } }\n }\n      pageInfo { hasNextPage endCursor }\n    }\n    team(id: $teamId) @include(if: $teamScoped) {\n      projects(filter: $filter, first: $first, after: $after, orderBy: updatedAt, includeArchived: false) {\n        nodes { \n  id\n  name\n  description\n  state\n  progress\n  targetDate\n  createdAt\n  updatedAt\n  lead { id name }\n  teams { nodes { id key name } }\n }\n        pageInfo { hasNextPage endCursor }\n      }\n    }\n  }\n";
+/** Batch label metadata and parent/team relations into one bounded catalog read. */
+export declare const GET_LABELS_CATALOG_QUERY = "\n  query GetLabelsCatalog($filter: IssueLabelFilter, $first: Int!) {\n    issueLabels(filter: $filter, first: $first) {\n      nodes {\n        id\n        name\n        color\n        isGroup\n        parent { id name }\n        team { id key name }\n      }\n    }\n  }\n";
+/** Batch cycle summaries and their team relation instead of resolving each edge. */
+export declare const GET_CYCLES_CATALOG_QUERY = "\n  query GetCyclesCatalog($filter: CycleFilter, $first: Int!) {\n    cycles(filter: $filter, first: $first, orderBy: createdAt) {\n      nodes {\n        id\n        name\n        number\n        startsAt\n        endsAt\n        isActive\n        isPrevious\n        isNext\n        progress\n        issueCountHistory\n        team { id key name }\n      }\n    }\n  }\n";
+/**
+ * Read one cycle and its bounded issue catalog in a single query, avoiding the
+ * SDK's per-issue relation fan-out while keeping the issue page size explicit.
+ */
+export declare const GET_CYCLE_DETAIL_QUERY = "\n  query GetCycleDetail($id: String!, $issuesFirst: Int!) {\n    cycle(id: $id) {\n      id\n      name\n      number\n      startsAt\n      endsAt\n      isActive\n      isPrevious\n      isNext\n      progress\n      issueCountHistory\n      team { id key name }\n      issues(first: $issuesFirst) {\n        nodes {\n          id\n          identifier\n          url\n          title\n          description\n          priority\n          estimate\n          createdAt\n          updatedAt\n          state { id name }\n          assignee { id name }\n          team { id key name }\n          project { id name }\n          labels { nodes { id name } }\n        }\n      }\n    }\n  }\n";
+/**
+ * Resolve a project name/slug with one bounded query. The conditional team
+ * branch performs scoping server-side without a separate project catalog read.
+ */
+export declare const RESOLVE_PROJECT_QUERY = "\n  query ResolveProjectCatalog(\n    $filter: ProjectFilter!\n\t\t$teamId: String!\n\t\t$teamScoped: Boolean!\n    $includeArchived: Boolean!\n  ) {\n    projects(filter: $filter, first: 5, includeArchived: $includeArchived) @skip(if: $teamScoped) {\n      nodes {\n        id\n        name\n        teams { nodes { id key name } }\n      }\n    }\n    team(id: $teamId) @include(if: $teamScoped) {\n      projects(filter: $filter, first: 5, includeArchived: $includeArchived) {\n        nodes {\n          id\n          name\n          teams { nodes { id key name } }\n        }\n      }\n    }\n  }\n";

package/dist/queries/catalog.js

@@ -0,0 +1,140 @@
+const PROJECT_FIELDS = `
+  id
+  name
+  description
+  state
+  progress
+  targetDate
+  createdAt
+  updatedAt
+  lead { id name }
+  teams { nodes { id key name } }
+`;
+/**
+ * Fetch project summaries, embedded teams, and lead in one paginated request.
+ * The conditional team branch replaces SDK relation follow-ups and keeps both
+ * request count and GraphQL complexity visible at one catalog boundary.
+ */
+export const GET_PROJECTS_CATALOG_QUERY = `
+  query GetProjectsCatalog(
+    $filter: ProjectFilter
+		$teamId: String!
+		$teamScoped: Boolean!
+    $first: Int!
+    $after: String
+  ) {
+    projects(filter: $filter, first: $first, after: $after, orderBy: updatedAt, includeArchived: false) @skip(if: $teamScoped) {
+      nodes { ${PROJECT_FIELDS} }
+      pageInfo { hasNextPage endCursor }
+    }
+    team(id: $teamId) @include(if: $teamScoped) {
+      projects(filter: $filter, first: $first, after: $after, orderBy: updatedAt, includeArchived: false) {
+        nodes { ${PROJECT_FIELDS} }
+        pageInfo { hasNextPage endCursor }
+      }
+    }
+  }
+`;
+/** Batch label metadata and parent/team relations into one bounded catalog read. */
+export const GET_LABELS_CATALOG_QUERY = `
+  query GetLabelsCatalog($filter: IssueLabelFilter, $first: Int!) {
+    issueLabels(filter: $filter, first: $first) {
+      nodes {
+        id
+        name
+        color
+        isGroup
+        parent { id name }
+        team { id key name }
+      }
+    }
+  }
+`;
+/** Batch cycle summaries and their team relation instead of resolving each edge. */
+export const GET_CYCLES_CATALOG_QUERY = `
+  query GetCyclesCatalog($filter: CycleFilter, $first: Int!) {
+    cycles(filter: $filter, first: $first, orderBy: createdAt) {
+      nodes {
+        id
+        name
+        number
+        startsAt
+        endsAt
+        isActive
+        isPrevious
+        isNext
+        progress
+        issueCountHistory
+        team { id key name }
+      }
+    }
+  }
+`;
+/**
+ * Read one cycle and its bounded issue catalog in a single query, avoiding the
+ * SDK's per-issue relation fan-out while keeping the issue page size explicit.
+ */
+export const GET_CYCLE_DETAIL_QUERY = `
+  query GetCycleDetail($id: String!, $issuesFirst: Int!) {
+    cycle(id: $id) {
+      id
+      name
+      number
+      startsAt
+      endsAt
+      isActive
+      isPrevious
+      isNext
+      progress
+      issueCountHistory
+      team { id key name }
+      issues(first: $issuesFirst) {
+        nodes {
+          id
+          identifier
+          url
+          title
+          description
+          priority
+          estimate
+          createdAt
+          updatedAt
+          state { id name }
+          assignee { id name }
+          team { id key name }
+          project { id name }
+          labels { nodes { id name } }
+        }
+      }
+    }
+  }
+`;
+/**
+ * Resolve a project name/slug with one bounded query. The conditional team
+ * branch performs scoping server-side without a separate project catalog read.
+ */
+export const RESOLVE_PROJECT_QUERY = `
+  query ResolveProjectCatalog(
+    $filter: ProjectFilter!
+		$teamId: String!
+		$teamScoped: Boolean!
+    $includeArchived: Boolean!
+  ) {
+    projects(filter: $filter, first: 5, includeArchived: $includeArchived) @skip(if: $teamScoped) {
+      nodes {
+        id
+        name
+        teams { nodes { id key name } }
+      }
+    }
+    team(id: $teamId) @include(if: $teamScoped) {
+      projects(filter: $filter, first: 5, includeArchived: $includeArchived) {
+        nodes {
+          id
+          name
+          teams { nodes { id key name } }
+        }
+      }
+    }
+  }
+`;

package/dist/utils/disk-cache.js

@@ -24,6 +24,7 @@
 import { randomBytes } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { withFileLock } from "../auth/oauth-fs.js";
 import { resolveActiveProfile } from "../config/paths.js";
 import { logger } from "./logger.js";
 const CACHE_VERSION = 1;
@@ -117,31 +118,64 @@ export async function cached(key, ttlSeconds, fetcher, options) {
     if (ttlSeconds <= 0) {
         return fetcher();
     }
-    const now = Date.now();
     if (!options?.bypass) {
         const envelope = await readEnvelope(key);
-        if (envelope && envelope.expiresAt > now) {
+        if (envelope && envelope.expiresAt > Date.now()) {
             return envelope.data;
         }
     }
-    const data = await fetcher();
-    const envelope = {
-        v: CACHE_VERSION,
-        key,
-        fetchedAt: now,
-        expiresAt: now + ttlSeconds * 1000,
-        data,
+    const fetchAndStore = async () => {
+        const data = await fetcher();
+        const now = Date.now();
+        const envelope = {
+            v: CACHE_VERSION,
+            key,
+            fetchedAt: now,
+            expiresAt: now + ttlSeconds * 1000,
+            data,
+        };
+        try {
+            await writeEnvelope(key, envelope);
+        }
+        catch (err) {
+            // Cache writes are best-effort — log to stderr and return the data
+            // anyway so a flaky disk doesn't break the user's command.
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error(`[disk-cache] write failed for "${key}": ${msg}`);
+        }
+        return data;
     };
+    // `--no-cache` is an explicit request to bypass both the cached value and
+    // cache coordination. Preserve that contract instead of making two forced
+    // refreshes wait on one another.
+    if (options?.bypass)
+        return fetchAndStore();
+    // Cold-cache single flight across processes. Re-read only after acquiring
+    // the sidecar lock: another el-linear invocation may have populated the
+    // envelope while this process was waiting. Without this second read, a
+    // burst of identical commands still sends one Linear request per process.
+    let enteredCriticalSection = false;
     try {
-        await writeEnvelope(key, envelope);
+        await fs.mkdir(cacheDir(), { recursive: true, mode: CACHE_DIR_MODE });
+        return await withFileLock(cachePath(key), async () => {
+            enteredCriticalSection = true;
+            const winner = await readEnvelope(key);
+            if (winner && winner.expiresAt > Date.now())
+                return winner.data;
+            return fetchAndStore();
+        });
     }
     catch (err) {
-        // Cache writes are best-effort — log to stderr and return the data
-        // anyway so a flaky disk doesn't break the user's command.
+        // Never retry a failed fetcher: a write may have reached Linear before
+        // throwing, so replaying it would be unsafe. Only coordination failures
+        // that happen before entering the critical section degrade to the old
+        // uncoordinated read-through behavior.
+        if (enteredCriticalSection)
+            throw err;
         const msg = err instanceof Error ? err.message : String(err);
-        logger.error(`[disk-cache] write failed for "${key}": ${msg}`);
+        logger.error(`[disk-cache] single-flight unavailable for "${key}": ${msg}`);
+        return fetchAndStore();
     }
-    return data;
 }
 /**
  * Clear cached entries. With no `prefix`, removes the entire cache