@enrichlayer/el-linear 1.17.0 → 1.18.1

package/README.md

@@ -247,6 +247,19 @@ 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.
 
+### Networking (IPv4 preference)
+
+el-linear talks only to `api.linear.app` (Cloudflare, dual-stack). On a network
+whose IPv6 route is broken or blackholed, Node's defaults (DNS result order
+`verbatim`, often IPv6-first, plus Happy Eyeballs) can make every call stall
+until it times out — surfacing as `GraphQL request failed: fetch failed`. To
+avoid that, el-linear prefers IPv4 by default (`ipv4first` DNS ordering with
+`autoSelectFamily` disabled).
+
+If you're on a **pure IPv6-only** network (no IPv4 route at all), set
+`EL_LINEAR_NETWORK_VERBATIM=1` to restore Node's native verbatim /
+Happy-Eyeballs behavior.
+
 ### Workspace URL key
 
 `refs wrap` and the auto-link paths build canonical issue URLs like

package/dist/commands/comments.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolveUserDisplayName } from "../config/resolver.js";
-import { CREATE_COMMENT_MUTATION, LIST_COMMENTS_QUERY, UPDATE_COMMENT_MUTATION, } from "../queries/comments.js";
+import { CREATE_COMMENT_MUTATION, DELETE_COMMENT_MUTATION, LIST_COMMENTS_QUERY, UPDATE_COMMENT_MUTATION, } from "../queries/comments.js";
 import { autoLinkReferences, } from "../utils/auto-link-references.js";
 import { applyFooter } from "../utils/footer.js";
 import { createGraphQLService, } from "../utils/graphql-service.js";
@@ -260,6 +260,15 @@ async function handleListComments(issueId, options, command) {
         },
     });
 }
+async function handleDeleteComment(commentId, _options, command) {
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const result = await graphQLService.rawRequest(DELETE_COMMENT_MUTATION, { id: commentId });
+    if (!result.commentDelete.success) {
+        throw new Error(`Failed to delete comment "${commentId}"`);
+    }
+    outputSuccess({ id: commentId, deleted: true });
+}
 export function setupCommentsCommands(program) {
     const comments = program
         .command("comments")
@@ -291,4 +300,11 @@ export function setupCommentsCommands(program) {
         .addHelpText("after", "\nBoth UUID and identifiers like ABC-123 are supported.")
         .option("-l, --limit <number>", "limit results", "25")
         .action(handleAsyncCommand(handleListComments));
+    comments
+        .command("delete <commentId>")
+        .alias("remove")
+        .alias("rm")
+        .description("Delete a comment by its id.")
+        .addHelpText("after", "\nTakes a comment id (the `id` field from `comments list` / `comments create`), not an issue identifier.")
+        .action(handleAsyncCommand(handleDeleteComment));
 }

package/dist/commands/issues/branch.d.ts

@@ -13,5 +13,52 @@ export declare function toBranchName(linearBranchName: string, prefix?: string):
 /**
  * Check out a new git branch. Warns and skips if not in a git repo.
  * Throws if the branch already exists.
+ *
+ * Returns `true` if the branch was actually checked out, `false` if the
+ * checkout was skipped (not in a git repo). Callers gate follow-on work
+ * (e.g. writing the `branch.<branch>.linearIssue` marker) on the result so
+ * they don't emit a second, contradictory warning about a branch that was
+ * never created.
+ */
+export declare function gitCheckoutBranch(branchName: string): boolean;
+/**
+ * Extract the canonical (uppercase) Linear identifier embedded in a branch
+ * name — `feature/DEV-4293-slug` → `DEV-4293`, `dev-4293-slug` → `DEV-4293`.
+ * Returns null when the branch carries no identifier token.
+ */
+export declare function extractIssueIdentifierFromBranch(branch: string): string | null;
+/**
+ * Record the Linear issue a branch implements as durable git metadata:
+ * `git config branch.<branch>.linearIssue <identifier>`. This is the signal
+ * DEV-4241's PreToolUse hook reads to confirm a workflow was established
+ * before allowing tracked-file edits — far more robust than parsing the
+ * branch name shape (which legitimately varies: `dev-4083-slug`,
+ * `fe-630-slug`, `emw-280-slug`), and it stays fast + offline (a local
+ * git config read, no API call).
+ *
+ * Best-effort by design: a failure to write the marker must never abort the
+ * issue-creation flow that triggered it. Callers in a known-good repo
+ * context wrap this and warn on failure; the standalone `mark-branch`
+ * command does its own repo/branch validation first so it can surface a
+ * clear error instead.
+ *
+ * No `--` ref-terminator (unlike the checkout/rename calls above): `git
+ * config <key> <value>` takes exactly two positional operands, the key is
+ * always our `branch.`-prefixed literal, and a value beginning with `-` is
+ * stored verbatim rather than parsed as a flag — so there's no
+ * flag-injection surface to defend here.
+ */
+export declare function setBranchLinearIssue(branch: string, identifier: string): void;
+/**
+ * Read back the `branch.<branch>.linearIssue` marker, or null when unset.
+ */
+export declare function getBranchLinearIssue(branch: string): string | null;
+/**
+ * Current branch's short name, or null when detached / not in a repo.
+ *
+ * Uses `symbolic-ref` rather than `rev-parse --abbrev-ref`: the former
+ * resolves the name even on an unborn branch (fresh repo, no commits yet)
+ * and still fails — yielding null — on a detached HEAD, which is exactly
+ * the "no named branch" signal callers want.
  */
-export declare function gitCheckoutBranch(branchName: string): void;
+export declare function currentGitBranch(): string | null;

package/dist/commands/issues/branch.js

@@ -25,6 +25,12 @@ export function toBranchName(linearBranchName, prefix = "feature/") {
 /**
  * Check out a new git branch. Warns and skips if not in a git repo.
  * Throws if the branch already exists.
+ *
+ * Returns `true` if the branch was actually checked out, `false` if the
+ * checkout was skipped (not in a git repo). Callers gate follow-on work
+ * (e.g. writing the `branch.<branch>.linearIssue` marker) on the result so
+ * they don't emit a second, contradictory warning about a branch that was
+ * never created.
  */
 export function gitCheckoutBranch(branchName) {
     try {
@@ -34,7 +40,7 @@ export function gitCheckoutBranch(branchName) {
     }
     catch {
         outputWarning("Not inside a git repository — skipping branch checkout.");
-        return;
+        return false;
     }
     // `--` separates the new-branch name from any ref. Without it, a
     // branch name starting with `-` (server bug, malicious team member
@@ -45,4 +51,78 @@ export function gitCheckoutBranch(branchName) {
     // prefix callers would lose the defense without this terminator.
     // Defense-in-depth (DEV-4064).
     execFileSync("git", ["checkout", "-b", branchName, "--"], { stdio: "pipe" });
+    return true;
+}
+// First Linear-style identifier token in a branch name, in any position, so
+// it survives a configurable prefix (`feature/DEV-123-slug`) and the bare
+// Linear shape (`dev-123-slug`). Anchored on a non-word boundary so it
+// doesn't match mid-token.
+const BRANCH_IDENTIFIER_REGEX = /(?:^|[^A-Za-z0-9])([A-Za-z]+-\d+)(?![A-Za-z0-9])/;
+/**
+ * Extract the canonical (uppercase) Linear identifier embedded in a branch
+ * name — `feature/DEV-4293-slug` → `DEV-4293`, `dev-4293-slug` → `DEV-4293`.
+ * Returns null when the branch carries no identifier token.
+ */
+export function extractIssueIdentifierFromBranch(branch) {
+    const match = branch.match(BRANCH_IDENTIFIER_REGEX);
+    return match ? match[1].toUpperCase() : null;
+}
+/**
+ * Record the Linear issue a branch implements as durable git metadata:
+ * `git config branch.<branch>.linearIssue <identifier>`. This is the signal
+ * DEV-4241's PreToolUse hook reads to confirm a workflow was established
+ * before allowing tracked-file edits — far more robust than parsing the
+ * branch name shape (which legitimately varies: `dev-4083-slug`,
+ * `fe-630-slug`, `emw-280-slug`), and it stays fast + offline (a local
+ * git config read, no API call).
+ *
+ * Best-effort by design: a failure to write the marker must never abort the
+ * issue-creation flow that triggered it. Callers in a known-good repo
+ * context wrap this and warn on failure; the standalone `mark-branch`
+ * command does its own repo/branch validation first so it can surface a
+ * clear error instead.
+ *
+ * No `--` ref-terminator (unlike the checkout/rename calls above): `git
+ * config <key> <value>` takes exactly two positional operands, the key is
+ * always our `branch.`-prefixed literal, and a value beginning with `-` is
+ * stored verbatim rather than parsed as a flag — so there's no
+ * flag-injection surface to defend here.
+ */
+export function setBranchLinearIssue(branch, identifier) {
+    execFileSync("git", ["config", `branch.${branch}.linearIssue`, identifier], {
+        stdio: "pipe",
+    });
+}
+/**
+ * Read back the `branch.<branch>.linearIssue` marker, or null when unset.
+ */
+export function getBranchLinearIssue(branch) {
+    try {
+        return execFileSync("git", ["config", "--get", `branch.${branch}.linearIssue`], { stdio: "pipe" })
+            .toString()
+            .trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Current branch's short name, or null when detached / not in a repo.
+ *
+ * Uses `symbolic-ref` rather than `rev-parse --abbrev-ref`: the former
+ * resolves the name even on an unborn branch (fresh repo, no commits yet)
+ * and still fails — yielding null — on a detached HEAD, which is exactly
+ * the "no named branch" signal callers want.
+ */
+export function currentGitBranch() {
+    try {
+        return execFileSync("git", ["symbolic-ref", "--short", "HEAD"], {
+            stdio: "pipe",
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return null;
+    }
 }

package/dist/commands/issues.js

@@ -17,7 +17,7 @@ import { handleAsyncCommand, outputSuccess, outputWarning, warnIfTruncated, } fr
 import { getRootOpts } from "../utils/root-opts.js";
 import { formatCsv, formatMarkdown, formatTable, } from "../utils/table-formatter.js";
 import { parsePositiveInt, parsePriorityFilter, splitList, validatePriority, } from "../utils/validators.js";
-import { gitCheckoutBranch, toBranchName } from "./issues/branch.js";
+import { currentGitBranch, extractIssueIdentifierFromBranch, getBranchLinearIssue, gitCheckoutBranch, setBranchLinearIssue, toBranchName, } from "./issues/branch.js";
 import { maybeAutoLink, prepareAutoLinkedDescription, readDescriptionFile, resolveDescription, } from "./issues/description.js";
 import { handleLinkReferencesIssue } from "./issues/link-references.js";
 import { buildIncomingRelationEntries, buildOutgoingRelationEntries, createRelations, } from "./issues/relations.js";
@@ -472,8 +472,25 @@ async function handleCreateIssue(title, options, command) {
     }
     let branch;
     if (options.checkout && result.branchName) {
-        branch = toBranchName(result.branchName);
-        gitCheckoutBranch(branch);
+        const branchName = toBranchName(result.branchName);
+        // Only treat the branch as created (and surface it in the output) when
+        // the checkout actually happened — outside a git repo gitCheckoutBranch
+        // warns and skips, and claiming a branch / a missing marker afterward
+        // would be a contradictory second warning (DEV-4293 cycle-1).
+        if (gitCheckoutBranch(branchName)) {
+            branch = branchName;
+            // Record the issue→branch link as git metadata (DEV-4293) so the
+            // DEV-4241 hook can confirm a workflow was established without parsing
+            // the branch name. Best-effort: never let a marker-write failure abort
+            // a successful issue creation.
+            try {
+                setBranchLinearIssue(branch, result.identifier);
+            }
+            catch {
+                outputWarning(`Created branch ${branch} but could not record its Linear issue marker. ` +
+                    `Run 'el-linear issues mark-branch ${result.identifier}' from the branch to set it.`);
+            }
+        }
     }
     const output = {
         ...result,
@@ -794,6 +811,14 @@ async function handleRetrolink(options, command) {
         execFileSync("git", ["branch", "-m", "--", oldBranch, newBranch], {
             stdio: "pipe",
         });
+        // Record the issue→branch link (DEV-4293), same as `create --checkout`.
+        try {
+            setBranchLinearIssue(newBranch, result.identifier);
+        }
+        catch {
+            outputWarning(`Renamed branch to ${newBranch} but could not record its Linear issue marker. ` +
+                `Run 'el-linear issues mark-branch ${result.identifier}' from the branch to set it.`);
+        }
     }
     outputSuccess({
         ...result,
@@ -801,6 +826,43 @@ async function handleRetrolink(options, command) {
         ...(newBranch ? { branch: newBranch } : {}),
     });
 }
+async function handleMarkBranch(issueId, _options, _command) {
+    const branch = currentGitBranch();
+    if (!branch) {
+        throw new Error("Not on a named git branch (detached HEAD or not in a repository).");
+    }
+    if (branch === "main" || branch === "master") {
+        throw new Error(`Refusing to mark the '${branch}' branch.`);
+    }
+    // Resolve the identifier to record. An explicit arg wins; otherwise infer
+    // it from the branch name. Both paths are offline — the marker's whole
+    // value is letting the hook verify a workflow without a network call, so
+    // we don't round-trip to the API just to normalize an identifier.
+    let identifier;
+    if (issueId) {
+        // Accepts a bare identifier (DEV-123), a branch-style token
+        // (dev-123-slug), or a Linear URL — extract normalizes all three.
+        identifier = extractIssueIdentifierFromBranch(issueId);
+        if (!identifier) {
+            throw new Error(`'${issueId}' is not a Linear issue identifier (expected a shape like DEV-123).`);
+        }
+    }
+    else {
+        identifier = extractIssueIdentifierFromBranch(branch);
+        if (!identifier) {
+            throw new Error(`Branch '${branch}' has no Linear identifier to infer. ` +
+                `Pass one explicitly: 'el-linear issues mark-branch DEV-123'.`);
+        }
+    }
+    const previous = getBranchLinearIssue(branch);
+    setBranchLinearIssue(branch, identifier);
+    outputSuccess({
+        branch,
+        linearIssue: identifier,
+        ...(previous && previous !== identifier ? { previous } : {}),
+        marked: true,
+    });
+}
 export function setupIssuesCommands(program) {
     const issues = program
         .command("issues")
@@ -1001,4 +1063,11 @@ export function setupIssuesCommands(program) {
         .option("--title <title>", "override auto-generated title (default: first commit message)")
         .option("--base <branch>", "base branch for log comparison", "main")
         .action(handleAsyncCommand(handleRetrolink));
+    issues
+        .command("mark-branch [issueId]")
+        .description("Record the current branch's Linear issue as git metadata (branch.<branch>.linearIssue).")
+        .addHelpText("after", "\nManual recovery for branches not created via 'issues create --checkout' / 'retrolink'.\n" +
+        "With no argument, infers the identifier from the branch name (e.g. dev-4293-slug -> DEV-4293).\n" +
+        "Accepts a bare identifier (DEV-123), a branch-style token, or a Linear URL.")
+        .action(handleAsyncCommand(handleMarkBranch));
 }

package/dist/main.js

@@ -28,9 +28,21 @@ import { setupTeamsCommands } from "./commands/teams.js";
 import { setupTemplatesCommands } from "./commands/templates.js";
 import { setupUsersCommands } from "./commands/users.js";
 import { setActiveProfileForSession } from "./config/paths.js";
+import { initCliSentry } from "./sentry.js";
+import { logger } from "./utils/logger.js";
+import { applyIpv4Preference } from "./utils/network-preference.js";
 import { setFieldsFilter, setJqFilter, setOutputFormat, setRawMode, } from "./utils/output.js";
 import { outputUsageInfo } from "./utils/usage.js";
 import { splitList } from "./utils/validators.js";
+// Prefer IPv4 for outbound API calls before any network I/O (Sentry init or a
+// command) runs — works around broken-IPv6 networks stalling Node's fetch.
+// Opt out with EL_LINEAR_NETWORK_VERBATIM=1. See DEV-4415 / network-preference.ts.
+const ipv4Preferred = applyIpv4Preference();
+if (process.env.EL_LINEAR_DEBUG ?? process.env.LINCTL_DEBUG) {
+    logger.error(ipv4Preferred
+        ? "[el-linear] network: preferring IPv4 (dns=ipv4first, autoSelectFamily=off)"
+        : "[el-linear] network: verbatim mode (EL_LINEAR_NETWORK_VERBATIM=1)");
+}
 // Read the version from package.json at startup so `--version` can never
 // drift from the published release (pre-fix: a stale 1.8.1 literal lived
 // here while package.json was at 1.10.0). `dist/main.js` lives one
@@ -38,6 +50,12 @@ import { splitList } from "./utils/validators.js";
 // correctly in both `pnpm dev` (tsx) and `node dist/main.js` invocations.
 const __dirname_main = dirname(fileURLToPath(import.meta.url));
 const packageJson = JSON.parse(readFileSync(join(__dirname_main, "..", "package.json"), "utf-8"));
+// Opt-in error reporting (DEV-4349): no-ops unless the namespaced SENTRY_DSN_CLI
+// env var is set AND the optional `@sentry/node` dependency is installed.
+// Fire-and-forget — the dynamic SDK import must never delay or break the CLI;
+// the global handlers it installs catch async failures once it resolves (a tick
+// later).
+void initCliSentry("el-linear", { version: packageJson.version });
 program
     .name("el-linear")
     .description("A pragmatic CLI for Linear.app — deterministic resolution, structured validation, GraphQL escape hatch.")

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

@@ -52,4 +52,9 @@ export interface UpdateCommentResponse {
         comment: UpdatedCommentResourceNode | null;
     };
 }
+export interface DeleteCommentResponse {
+    commentDelete: {
+        success: boolean;
+    };
+}
 export {};

package/dist/queries/comments.d.ts

@@ -1,3 +1,4 @@
 export declare const LIST_COMMENTS_QUERY = "\n  query ListComments($issueId: String!, $first: Int) {\n    issue(id: $issueId) {\n      id\n      identifier\n      comments(first: $first, orderBy: createdAt) {\n        nodes {\n          id\n          body\n          createdAt\n          updatedAt\n          user {\n            id\n            name\n            displayName\n            url\n          }\n        }\n      }\n    }\n  }\n";
 export declare const CREATE_COMMENT_MUTATION = "\n  mutation CreateComment($input: CommentCreateInput!) {\n    commentCreate(input: $input) {\n      success\n      comment {\n        id\n        body\n        createdAt\n        updatedAt\n        user {\n          id\n          name\n          displayName\n          url\n        }\n      }\n    }\n  }\n";
 export declare const UPDATE_COMMENT_MUTATION = "\n  mutation UpdateComment($id: String!, $input: CommentUpdateInput!) {\n    commentUpdate(id: $id, input: $input) {\n      success\n      comment {\n        id\n        body\n        createdAt\n        updatedAt\n        user {\n          id\n          name\n          displayName\n          url\n        }\n        issue {\n          id\n          identifier\n        }\n      }\n    }\n  }\n";
+export declare const DELETE_COMMENT_MUTATION = "\n  mutation DeleteComment($id: String!) {\n    commentDelete(id: $id) {\n      success\n    }\n  }\n";

package/dist/queries/comments.js

@@ -62,3 +62,16 @@ export const UPDATE_COMMENT_MUTATION = `
     }
   }
 `;
+// commentDelete returns a DeletePayload (`{ success }`) — no `comment` node,
+// since the entity is gone. The @linear/sdk exposes this as
+// `client.deleteComment(id)`, but the standalone comment commands all go
+// through raw mutations on `graphQLService` (create/update need `bodyData`,
+// which the SDK's typed input wraps awkwardly), so delete stays on the same
+// raw path for a consistent, single-mock test surface.
+export const DELETE_COMMENT_MUTATION = `
+  mutation DeleteComment($id: String!) {
+    commentDelete(id: $id) {
+      success
+    }
+  }
+`;

package/dist/sentry.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Optional, opt-in Sentry error reporting for el-linear (DEV-4349, sub of DEV-4328).
+ *
+ * el-linear ships open-source, so Sentry is NEVER required:
+ *  - No dependency on the private `@enrichlayer/sentry` package — this is a
+ *    self-contained copy of its scrub + init (acceptable duplication: the repo
+ *    boundary makes sharing the tools-repo util impossible).
+ *  - `@sentry/node` is an OPTIONAL dependency, loaded via a dynamic
+ *    `import("@sentry/node")` ONLY when a DSN resolves. `npm i @enrichlayer/el-linear`
+ *    never forces Sentry, and a missing/uninstalled SDK is a clean no-op.
+ *  - The DSN comes from the environment only (`SENTRY_DSN_CLI`) — no Vault (that
+ *    is internal infra OSS users do not have), and NOT the conventional
+ *    `SENTRY_DSN` (which would collide with an OSS user's own app). Default OFF;
+ *    only active when we set our namespaced env var in our own environment.
+ *
+ * One line at the top of `main.ts`:
+ *
+ *   import { initCliSentry } from "./sentry.js";
+ *   void initCliSentry("el-linear", { version });
+ *   // ... program.parse()
+ *
+ * Set `EL_SENTRY_DISABLED=1` to force-disable even when a DSN is present.
+ *
+ * Safety: a mandatory `beforeSend` scrub redacts secret-shaped values (tokens,
+ * keys, auth headers). CLI argv/env routinely carry credentials (the Linear API
+ * token, GitHub PATs), and an unscrubbed report would leak them into Sentry.
+ */
+/** A Sentry event is deeply dynamic; we walk it structurally. */
+type Json = unknown;
+export declare const REDACTED = "[redacted]";
+/** Redact credential-shaped substrings from a string. Pure. */
+export declare function scrubString(input: string): string;
+/**
+ * Recursively scrub a JSON-ish value: redact whole values under secret-named
+ * keys, scrub credential-shaped substrings everywhere else, and cap depth so a
+ * cyclic / huge event can't hang the scrubber. Pure.
+ */
+export declare function scrubValue(value: Json, depth?: number): Json;
+/**
+ * Scrub a Sentry event (message, exceptions, breadcrumbs, extra, request — which
+ * carries headers + env — and contexts) by walking it structurally. Pure.
+ */
+export declare function scrubEvent(event: Json): Json;
+/**
+ * Resolve the CLI Sentry DSN from the environment. Returns null when reporting
+ * is disabled or no DSN is configured (→ init no-ops). No Vault: OSS users do
+ * not have it, so this path is intentionally env-only.
+ *
+ * Only the namespaced `SENTRY_DSN_CLI` is read — NOT the conventional
+ * `SENTRY_DSN`. el-linear ships open-source, and `SENTRY_DSN` is the var the
+ * `@sentry/node` SDK reads by default, so an OSS user running their own
+ * Sentry-instrumented app very likely has it set; falling back to it would make
+ * el-linear silently report into *their* project. Requiring our explicit,
+ * namespaced var keeps activation unambiguous and collision-free (DEV-4349
+ * cycle-1 review). The internal tools build uses `SENTRY_DSN_CLI` too, so we
+ * lose nothing.
+ */
+export declare function resolveDsn(): string | null;
+export interface InitCliSentryOptions {
+    /** Override the resolved DSN (mainly for tests). */
+    dsn?: string | null;
+    /** CLI version for the Sentry `release` (defaults to "0.0.0"). */
+    version?: string;
+}
+/**
+ * Initialize Sentry for el-linear. Async because `@sentry/node` is loaded via a
+ * dynamic import only when a DSN resolves — so a CLI run without a DSN (the
+ * default for OSS users) never even loads the SDK. Returns true when reporting
+ * is active, false when it no-ops (disabled / no DSN / SDK not installed).
+ *
+ * When active, installs global uncaughtException + unhandledRejection handlers
+ * that capture → flush → exit(1). Because the SDK loads via a dynamic import
+ * (resolving a tick after the caller's fire-and-forget `void`), a synchronous
+ * throw during the very first tick of CLI startup — before the handlers install
+ * — is out of scope; this is best-effort reporting, not a crash guarantee.
+ */
+export declare function initCliSentry(cliName: string, opts?: InitCliSentryOptions): Promise<boolean>;
+export {};

package/dist/sentry.js

@@ -0,0 +1,150 @@
+/**
+ * Optional, opt-in Sentry error reporting for el-linear (DEV-4349, sub of DEV-4328).
+ *
+ * el-linear ships open-source, so Sentry is NEVER required:
+ *  - No dependency on the private `@enrichlayer/sentry` package — this is a
+ *    self-contained copy of its scrub + init (acceptable duplication: the repo
+ *    boundary makes sharing the tools-repo util impossible).
+ *  - `@sentry/node` is an OPTIONAL dependency, loaded via a dynamic
+ *    `import("@sentry/node")` ONLY when a DSN resolves. `npm i @enrichlayer/el-linear`
+ *    never forces Sentry, and a missing/uninstalled SDK is a clean no-op.
+ *  - The DSN comes from the environment only (`SENTRY_DSN_CLI`) — no Vault (that
+ *    is internal infra OSS users do not have), and NOT the conventional
+ *    `SENTRY_DSN` (which would collide with an OSS user's own app). Default OFF;
+ *    only active when we set our namespaced env var in our own environment.
+ *
+ * One line at the top of `main.ts`:
+ *
+ *   import { initCliSentry } from "./sentry.js";
+ *   void initCliSentry("el-linear", { version });
+ *   // ... program.parse()
+ *
+ * Set `EL_SENTRY_DISABLED=1` to force-disable even when a DSN is present.
+ *
+ * Safety: a mandatory `beforeSend` scrub redacts secret-shaped values (tokens,
+ * keys, auth headers). CLI argv/env routinely carry credentials (the Linear API
+ * token, GitHub PATs), and an unscrubbed report would leak them into Sentry.
+ */
+/** Key names whose values are always redacted, regardless of content. */
+const SECRET_KEY_RE = /(token|secret|passwd|password|api[_-]?key|apikey|bearer|authorization|auth|dsn|cookie|session|credential|private[_-]?key)/i;
+/** Value patterns that look like a credential even under an innocent key. */
+const SECRET_VALUE_RES = [
+    /glpat-[A-Za-z0-9_-]{10,}/g, // GitLab PAT
+    /gh[pousr]_[A-Za-z0-9]{20,}/g, // GitHub classic token
+    /github_pat_[A-Za-z0-9_]{20,}/g, // GitHub fine-grained PAT (now the default)
+    /xox[baprs]-[A-Za-z0-9-]{10,}/g, // Slack bot/user token
+    /xapp-[A-Za-z0-9-]{10,}/g, // Slack app-level token
+    /lin_api_[A-Za-z0-9]{20,}/g, // Linear API key
+    /sk-[A-Za-z0-9]{16,}/g, // OpenAI-style key
+    /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, // JWT
+    /\b[Bb]earer\s+[A-Za-z0-9._-]{10,}/g, // bearer header
+    /https?:\/\/[^:@/\s]+:[^@/\s]+@/g, // creds in a URL (user:pass@host)
+];
+export const REDACTED = "[redacted]";
+const MAX_DEPTH = 8;
+/** Redact credential-shaped substrings from a string. Pure. */
+export function scrubString(input) {
+    let out = input;
+    for (const re of SECRET_VALUE_RES) {
+        out = out.replace(re, REDACTED);
+    }
+    return out;
+}
+/**
+ * Recursively scrub a JSON-ish value: redact whole values under secret-named
+ * keys, scrub credential-shaped substrings everywhere else, and cap depth so a
+ * cyclic / huge event can't hang the scrubber. Pure.
+ */
+export function scrubValue(value, depth = 0) {
+    if (depth > MAX_DEPTH) {
+        // Fail CLOSED: past the cap we can't recurse to check for secrets, so a
+        // primitive could be a credential — redact rather than leak it.
+        return REDACTED;
+    }
+    if (typeof value === "string") {
+        return scrubString(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => scrubValue(v, depth + 1));
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = SECRET_KEY_RE.test(k) ? REDACTED : scrubValue(v, depth + 1);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Scrub a Sentry event (message, exceptions, breadcrumbs, extra, request — which
+ * carries headers + env — and contexts) by walking it structurally. Pure.
+ */
+export function scrubEvent(event) {
+    return scrubValue(event);
+}
+/**
+ * Resolve the CLI Sentry DSN from the environment. Returns null when reporting
+ * is disabled or no DSN is configured (→ init no-ops). No Vault: OSS users do
+ * not have it, so this path is intentionally env-only.
+ *
+ * Only the namespaced `SENTRY_DSN_CLI` is read — NOT the conventional
+ * `SENTRY_DSN`. el-linear ships open-source, and `SENTRY_DSN` is the var the
+ * `@sentry/node` SDK reads by default, so an OSS user running their own
+ * Sentry-instrumented app very likely has it set; falling back to it would make
+ * el-linear silently report into *their* project. Requiring our explicit,
+ * namespaced var keeps activation unambiguous and collision-free (DEV-4349
+ * cycle-1 review). The internal tools build uses `SENTRY_DSN_CLI` too, so we
+ * lose nothing.
+ */
+export function resolveDsn() {
+    if (process.env.EL_SENTRY_DISABLED === "1") {
+        return null;
+    }
+    return process.env.SENTRY_DSN_CLI?.trim() || null;
+}
+/**
+ * Initialize Sentry for el-linear. Async because `@sentry/node` is loaded via a
+ * dynamic import only when a DSN resolves — so a CLI run without a DSN (the
+ * default for OSS users) never even loads the SDK. Returns true when reporting
+ * is active, false when it no-ops (disabled / no DSN / SDK not installed).
+ *
+ * When active, installs global uncaughtException + unhandledRejection handlers
+ * that capture → flush → exit(1). Because the SDK loads via a dynamic import
+ * (resolving a tick after the caller's fire-and-forget `void`), a synchronous
+ * throw during the very first tick of CLI startup — before the handlers install
+ * — is out of scope; this is best-effort reporting, not a crash guarantee.
+ */
+export async function initCliSentry(cliName, opts = {}) {
+    const dsn = opts.dsn === undefined ? resolveDsn() : opts.dsn;
+    if (!dsn) {
+        return false;
+    }
+    let Sentry;
+    try {
+        // Optional dependency: loaded only here, only when a DSN is set. A
+        // missing/uninstalled SDK is a clean no-op (we never ship Sentry to OSS
+        // users who have not opted in).
+        Sentry = (await import("@sentry/node"));
+    }
+    catch {
+        return false;
+    }
+    Sentry.init({
+        dsn,
+        release: `${cliName}@${opts.version ?? "0.0.0"}`,
+        environment: process.env.CI ? "ci" : "development",
+        tracesSampleRate: 0,
+        beforeSend: (event) => scrubEvent(event),
+    });
+    Sentry.setTag("cli", cliName);
+    const report = (err) => {
+        Sentry.captureException(err);
+        // Flush before exiting; the process is in an undefined state after an
+        // uncaught error, so report-then-die is the standard Sentry pattern.
+        Sentry.flush(2000).then(() => process.exit(1), () => process.exit(1));
+    };
+    process.on("uncaughtException", report);
+    process.on("unhandledRejection", (reason) => report(reason instanceof Error ? reason : new Error(String(reason))));
+    return true;
+}

package/dist/utils/graphql-issues-service.js

@@ -359,7 +359,7 @@ export class GraphQLIssuesService {
         const finalProjectId = projectIdArg
             ? this.resolveProjectId(projectIdArg, resolveResult)
             : undefined;
-        const finalAssigneeId = this.resolveAssigneeId(args.assigneeId, resolveResult);
+        const finalAssigneeId = await this.resolveAssigneeId(args.assigneeId, resolveResult);
         const finalDelegateId = await this.resolveDelegateId(args.delegateId, resolveResult);
         // Map the public discriminant back to the internal filter shape:
         // `{ kind: "id", id }` → `{ kind: "id", id: <resolvedUuid> }`
@@ -877,10 +877,20 @@ export class GraphQLIssuesService {
         }
         return filter;
     }
-    resolveAssigneeId(assigneeId, resolveResult) {
-        if (!assigneeId || isUuid(assigneeId) || !assigneeId.includes("@")) {
+    async resolveAssigneeId(assigneeId, resolveResult) {
+        if (!assigneeId || isUuid(assigneeId)) {
             return assigneeId;
         }
+        // A plain name (no `@`) resolves via the user lookup — same as
+        // `resolveDelegateId`. Without this, a non-config full name like
+        // "Yury Tsukerman" fell through unchanged and was sent to the
+        // GraphQL filter as a bogus UUID, producing an opaque "Argument
+        // Validation Error" instead of resolving (or a clean not-found).
+        // `resolveUserId` matches displayName then name and throws a
+        // structured notFound / multiple-matches error (DEV-4312).
+        if (!assigneeId.includes("@")) {
+            return this.linearService.resolveUserId(assigneeId);
+        }
         const userNodes = resolveResult.users?.nodes;
         if (!userNodes?.length) {
             throw notFoundError("User", assigneeId);

package/dist/utils/network-preference.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Injectable seams for the two Node defaults we flip. Real callers use the
+ * `node:dns` / `node:net` implementations; tests pass spies.
+ */
+export interface NetworkPreferenceDeps {
+    setDefaultResultOrder: (order: "ipv4first" | "ipv6first" | "verbatim") => void;
+    setDefaultAutoSelectFamily: (value: boolean) => void;
+}
+/** Set this env var to `1` to keep Node's native behavior (see below). */
+export declare const VERBATIM_ENV = "EL_LINEAR_NETWORK_VERBATIM";
+/**
+ * Prefer IPv4 for el-linear's outbound API calls.
+ *
+ * el-linear talks only to `api.linear.app` (Cloudflare, dual-stack — it
+ * publishes AAAA records). On a network whose IPv6 route is broken or
+ * blackholed, Node 17+'s defaults — DNS result order `verbatim` (often
+ * IPv6-first) plus Happy Eyeballs (`autoSelectFamily`) — make `fetch`
+ * (undici) stall on the dead IPv6 path until it times out, surfacing as
+ * `GraphQL request failed: fetch failed`. Restoring `ipv4first` AND disabling
+ * `autoSelectFamily` makes el-linear use the working IPv4 path directly.
+ * (`ipv4first` alone is not enough — Happy Eyeballs still races the dead IPv6
+ * address; both levers are required.) `ipv4first` was Node's own default
+ * before v17, so this is a conservative choice.
+ *
+ * Opt out with `EL_LINEAR_NETWORK_VERBATIM=1` — required only on pure
+ * IPv6-only networks (no IPv4 route at all), where preferring IPv4 would pick
+ * an unreachable address. See DEV-4415.
+ *
+ * @returns `true` if the IPv4 preference was applied, `false` if opted out.
+ */
+export declare function applyIpv4Preference(env?: NodeJS.ProcessEnv, deps?: NetworkPreferenceDeps): boolean;

package/dist/utils/network-preference.js

@@ -0,0 +1,37 @@
+import dns from "node:dns";
+import net from "node:net";
+const defaultDeps = {
+    // Wrapped (not passed by reference) so the receiver keeps its module binding.
+    setDefaultResultOrder: (order) => dns.setDefaultResultOrder(order),
+    setDefaultAutoSelectFamily: (value) => net.setDefaultAutoSelectFamily(value),
+};
+/** Set this env var to `1` to keep Node's native behavior (see below). */
+export const VERBATIM_ENV = "EL_LINEAR_NETWORK_VERBATIM";
+/**
+ * Prefer IPv4 for el-linear's outbound API calls.
+ *
+ * el-linear talks only to `api.linear.app` (Cloudflare, dual-stack — it
+ * publishes AAAA records). On a network whose IPv6 route is broken or
+ * blackholed, Node 17+'s defaults — DNS result order `verbatim` (often
+ * IPv6-first) plus Happy Eyeballs (`autoSelectFamily`) — make `fetch`
+ * (undici) stall on the dead IPv6 path until it times out, surfacing as
+ * `GraphQL request failed: fetch failed`. Restoring `ipv4first` AND disabling
+ * `autoSelectFamily` makes el-linear use the working IPv4 path directly.
+ * (`ipv4first` alone is not enough — Happy Eyeballs still races the dead IPv6
+ * address; both levers are required.) `ipv4first` was Node's own default
+ * before v17, so this is a conservative choice.
+ *
+ * Opt out with `EL_LINEAR_NETWORK_VERBATIM=1` — required only on pure
+ * IPv6-only networks (no IPv4 route at all), where preferring IPv4 would pick
+ * an unreachable address. See DEV-4415.
+ *
+ * @returns `true` if the IPv4 preference was applied, `false` if opted out.
+ */
+export function applyIpv4Preference(env = process.env, deps = defaultDeps) {
+    if (env[VERBATIM_ENV] === "1") {
+        return false;
+    }
+    deps.setDefaultResultOrder("ipv4first");
+    deps.setDefaultAutoSelectFamily(false);
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.17.0",
+  "version": "1.18.1",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",
@@ -64,6 +64,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.0.18"
   },
+  "optionalDependencies": {
+    "@sentry/node": "^10.50.0"
+  },
   "scripts": {
     "build": "tsc && chmod +x dist/main.js",
     "clean": "rm -rf dist/",