@enrichlayer/el-linear 1.19.0 → 1.21.0

package/dist/queries/issue-tree.js

@@ -0,0 +1,67 @@
+/**
+ * Tree-fetch query builder for `issues tree <ID>` (DEV-4480).
+ *
+ * GraphQL has no native depth-N recursion, so the query is generated by
+ * nesting `children { nodes { ... } }` N times at build time. This keeps
+ * the *fetch* to a single round-trip even for deep trees, at the cost of
+ * a larger query string.
+ *
+ * Each level fetches the minimal field set needed to render a tree entry:
+ * id, identifier, title, state.{name,type}, assignee.name. State.type is
+ * present so the renderer can flag terminal states (Done / Canceled) and
+ * the caller's `--include-closed` filter can be applied client-side after
+ * the fetch (Linear doesn't accept a top-level filter that scopes to the
+ * issue subtree — the children connection is filterless).
+ *
+ * Depth bounds: `1` (just the root + its direct children) through `5`.
+ * Above 5 the query string grows too large to be useful as a single call;
+ * callers wanting deeper walks should iterate `tree` on leaf nodes.
+ */
+export const MIN_TREE_DEPTH = 1;
+export const MAX_TREE_DEPTH = 5;
+export const DEFAULT_TREE_DEPTH = 3;
+// Field set per tree node — kept minimal so the depth-N query stays small.
+// `state.type` is required client-side for `--no-include-closed` pruning;
+// `state.name` for the [Done]/[Canceled] suffix on terminal nodes.
+// `priority` was intentionally dropped after cycle-1: the ASCII formatter
+// doesn't render it and including it inflates the query string by ~N nodes.
+const TREE_NODE_FIELDS = `
+	id
+	identifier
+	title
+	state { id name type }
+	assignee { id name }
+`;
+/**
+ * Recursive children fragment generator. `depth=0` emits nothing (no
+ * children fetched at this level — terminal); `depth=1` emits a single
+ * `children { nodes { ...fields } }`; higher depths nest further.
+ */
+function buildChildrenBlock(depth) {
+    if (depth <= 0) {
+        return "";
+    }
+    return `
+		children {
+			nodes {
+				${TREE_NODE_FIELDS}
+				${buildChildrenBlock(depth - 1)}
+			}
+		}
+	`;
+}
+export function buildIssueTreeQuery(depth) {
+    if (!Number.isInteger(depth) ||
+        depth < MIN_TREE_DEPTH ||
+        depth > MAX_TREE_DEPTH) {
+        throw new Error(`Tree depth must be an integer in [${MIN_TREE_DEPTH}, ${MAX_TREE_DEPTH}]; got ${depth}`);
+    }
+    return `
+		query GetIssueTree($id: String!) {
+			issue(id: $id) {
+				${TREE_NODE_FIELDS}
+				${buildChildrenBlock(depth)}
+			}
+		}
+	`;
+}

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

@@ -25,6 +25,12 @@ import type { LinearPriority } from "../types/linear.js";
 interface IdNameRef {
     id: string;
     name: string;
+    /**
+     * Workflow-state type — selected only on state fragments. Optional so
+     * non-state IdNameRef users (project, team, assignee, etc.) stay valid.
+     * DEV-4478.
+     */
+    type?: string;
 }
 interface IdKeyNameRef {
     id: string;
@@ -134,6 +140,12 @@ export interface GetIssueByIdentifierResponse {
         nodes: IssueWithCommentsNode[];
     };
 }
+/** Response shape for `BATCH_GET_ISSUES_QUERY` (DEV-4477). */
+export interface BatchGetIssuesResponse {
+    issues: {
+        nodes: IssueWithCommentsNode[];
+    };
+}
 /** Response shape for `GET_ISSUES_QUERY`. */
 export interface GetIssuesResponse {
     issues: {

package/dist/queries/issues.d.ts

@@ -1,6 +1,6 @@
-export declare const GET_ISSUES_QUERY = "\n  query GetIssues($first: Int!, $orderBy: PaginationOrderBy) {\n    issues(\n      first: $first\n      orderBy: $orderBy\n      filter: {\n        state: { type: { neq: \"completed\" } }\n      }\n    ) {\n      nodes {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
-export declare const SEARCH_ISSUES_QUERY = "\n  query SearchIssues($term: String!, $first: Int!) {\n    searchIssues(term: $term, first: $first, includeArchived: false) {\n      nodes {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
-export declare const FILTERED_SEARCH_ISSUES_QUERY = "\n  query FilteredSearchIssues(\n    $first: Int!\n    $filter: IssueFilter\n    $orderBy: PaginationOrderBy\n  ) {\n    issues(\n      first: $first\n      filter: $filter\n      orderBy: $orderBy\n      includeArchived: false\n    ) {\n      nodes {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
+export declare const GET_ISSUES_QUERY = "\n  query GetIssues($first: Int!, $orderBy: PaginationOrderBy) {\n    issues(\n      first: $first\n      orderBy: $orderBy\n      filter: {\n        state: { type: { neq: \"completed\" } }\n      }\n    ) {\n      nodes {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
+export declare const SEARCH_ISSUES_QUERY = "\n  query SearchIssues($term: String!, $first: Int!) {\n    searchIssues(term: $term, first: $first, includeArchived: false) {\n      nodes {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
+export declare const FILTERED_SEARCH_ISSUES_QUERY = "\n  query FilteredSearchIssues(\n    $first: Int!\n    $filter: IssueFilter\n    $orderBy: PaginationOrderBy\n  ) {\n    issues(\n      first: $first\n      filter: $filter\n      orderBy: $orderBy\n      includeArchived: false\n    ) {\n      nodes {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
 /**
  * Batch-resolves a search's team/project/assignee/delegate filter inputs.
  *
@@ -11,8 +11,30 @@ export declare const FILTERED_SEARCH_ISSUES_QUERY = "\n  query FilteredSearchIss
  * name-resolution arm is needed here.)
  */
 export declare const BATCH_RESOLVE_FOR_SEARCH_QUERY = "\n  query BatchResolveForSearch(\n    $teamKey: String\n    $teamName: String\n    $projectName: String\n    $hasProjectName: Boolean = false\n    $assigneeEmail: String\n    $delegateEmail: String\n  ) {\n    teams(\n      filter: {\n        or: [\n          { key: { eq: $teamKey } }\n          { name: { eqIgnoreCase: $teamName } }\n        ]\n      }\n      first: 1\n    ) {\n      nodes {\n        id\n        key\n        name\n      }\n    }\n\n    projects(\n      filter: { name: { eqIgnoreCase: $projectName } }\n      first: 1\n    ) @include(if: $hasProjectName) {\n      nodes {\n        id\n        name\n      }\n    }\n\n    users(filter: { email: { eq: $assigneeEmail } }, first: 1) {\n      nodes {\n        id\n        name\n        email\n      }\n    }\n\n    delegates: users(filter: { email: { eq: $delegateEmail } }, first: 1) {\n      nodes {\n        id\n        name\n        email\n      }\n    }\n  }\n";
-export declare const GET_ISSUE_BY_ID_QUERY = "\n  query GetIssue($id: String!) {\n    issue(id: $id) {\n      \n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n\n    }\n  }\n";
-export declare const GET_ISSUE_BY_IDENTIFIER_QUERY = "\n  query GetIssueByIdentifier($teamKey: String!, $number: Float!) {\n    issues(\n      filter: {\n        team: { key: { eq: $teamKey } }\n        number: { eq: $number }\n      }\n      first: 1\n    ) {\n      nodes {\n        \n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n\n      }\n    }\n  }\n";
+export declare const GET_ISSUE_BY_ID_QUERY = "\n  query GetIssue($id: String!) {\n    issue(id: $id) {\n      \n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n\n    }\n  }\n";
+export declare const GET_ISSUE_BY_IDENTIFIER_QUERY = "\n  query GetIssueByIdentifier($teamKey: String!, $number: Float!) {\n    issues(\n      filter: {\n        team: { key: { eq: $teamKey } }\n        number: { eq: $number }\n      }\n      first: 1\n    ) {\n      nodes {\n        \n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n\n      }\n    }\n  }\n";
+/**
+ * Batch issue fetch. Used by `issues read <id...>` (DEV-4477) to collapse
+ * N parallel single-issue queries into one round-trip. The `$filter` is
+ * a top-level OR built client-side; each OR clause is either:
+ *   { id: { in: [...uuids] } }                                  ← all UUIDs in one IN
+ *   { team: { key: { eq: <key> } }, number: { in: [...nums] } } ← identifiers
+ *                                                                  grouped by team
+ * Linear returns nodes in DB order, NOT input order — the caller is
+ * responsible for re-sorting to match the input list before surfacing.
+ *
+ * `$first` is `refCount * 2`, clamped to [100, 250] — the floor absorbs the
+ * rare case where Linear returns more rows than requested via OR-clause
+ * collisions; the ceiling is Linear's connection-page cap, beyond which the
+ * server silently truncates.
+ *
+ * Raw GraphQL (not @linear/sdk) is required because the SDK's
+ * `client.issues({ filter: ... })` strips through the same query under
+ * the hood but forces one round-trip per call site; the doctrine in
+ * CLAUDE.md ("Performance-critical loops where the SDK's per-edge
+ * resolver promises produce N+1 round-trips") explicitly authorizes this.
+ */
+export declare const BATCH_GET_ISSUES_QUERY = "\n  query BatchGetIssues($filter: IssueFilter!, $first: Int!) {\n    issues(filter: $filter, first: $first) {\n      nodes {\n        \n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n\n      }\n    }\n  }\n";
 /**
  * Batch-resolves an update's project/milestone/issue inputs.
  *
@@ -23,8 +45,8 @@ export declare const GET_ISSUE_BY_IDENTIFIER_QUERY = "\n  query GetIssueByIdenti
  * `--project-milestone` name resolution; a name uses `projectsByName`.
  */
 export declare const BATCH_RESOLVE_FOR_UPDATE_QUERY = "\n  query BatchResolveForUpdate(\n    $projectName: String\n    $projectId: ID\n    $hasProjectName: Boolean = false\n    $hasProjectId: Boolean = false\n    $teamKey: String\n    $issueNumber: Float\n    $milestoneName: String\n    $hasMilestoneName: Boolean = false\n  ) {\n    projectsByName: projects(\n      filter: { name: { eqIgnoreCase: $projectName } }\n      first: 5\n    ) @include(if: $hasProjectName) {\n      nodes {\n        id\n        name\n        teams {\n          nodes { id key }\n        }\n        projectMilestones {\n          nodes {\n            id\n            name\n          }\n        }\n      }\n    }\n\n    projectsById: projects(\n      filter: { id: { eq: $projectId } }\n      first: 1\n    ) @include(if: $hasProjectId) {\n      nodes {\n        id\n        name\n        projectMilestones {\n          nodes {\n            id\n            name\n          }\n        }\n      }\n    }\n\n    milestones: projectMilestones(\n      filter: { name: { eq: $milestoneName } }\n      first: 1\n    ) @include(if: $hasMilestoneName) {\n      nodes {\n        id\n        name\n      }\n    }\n\n    issues(\n      filter: {\n        and: [\n          { team: { key: { eq: $teamKey } } }\n          { number: { eq: $issueNumber } }\n        ]\n      }\n      first: 1\n    ) {\n      nodes {\n        id\n        identifier\n        team {\n          id\n          key\n        }\n        labels {\n          nodes {\n            id\n            name\n          }\n        }\n        project {\n          id\n          projectMilestones {\n            nodes {\n              id\n              name\n            }\n          }\n        }\n      }\n    }\n  }\n";
-export declare const CREATE_ISSUE_MUTATION = "\n  mutation CreateIssue($input: IssueCreateInput!) {\n    issueCreate(input: $input) {\n      success\n      issue {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
-export declare const UPDATE_ISSUE_MUTATION = "\n  mutation UpdateIssue($id: String!, $input: IssueUpdateInput!) {\n    issueUpdate(id: $id, input: $input) {\n      success\n      issue {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
+export declare const CREATE_ISSUE_MUTATION = "\n  mutation CreateIssue($input: IssueCreateInput!) {\n    issueCreate(input: $input) {\n      success\n      issue {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
+export declare const UPDATE_ISSUE_MUTATION = "\n  mutation UpdateIssue($id: String!, $input: IssueUpdateInput!) {\n    issueUpdate(id: $id, input: $input) {\n      success\n      issue {\n        \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n      }\n    }\n  }\n";
 export declare const ARCHIVE_ISSUE_MUTATION = "\n  mutation ArchiveIssue($id: String!) {\n    issueArchive(id: $id) {\n      success\n      lastSyncId\n      entity {\n        id\n      }\n    }\n  }\n";
 export declare const DELETE_ISSUE_MUTATION = "\n  mutation DeleteIssue($id: String!, $permanentlyDelete: Boolean) {\n    issueDelete(id: $id, permanentlyDelete: $permanentlyDelete) {\n      success\n      lastSyncId\n      entity {\n        id\n      }\n    }\n  }\n";
 /**

package/dist/queries/issues.js

@@ -124,6 +124,36 @@ export const GET_ISSUE_BY_IDENTIFIER_QUERY = `
     }
   }
 `;
+/**
+ * Batch issue fetch. Used by `issues read <id...>` (DEV-4477) to collapse
+ * N parallel single-issue queries into one round-trip. The `$filter` is
+ * a top-level OR built client-side; each OR clause is either:
+ *   { id: { in: [...uuids] } }                                  ← all UUIDs in one IN
+ *   { team: { key: { eq: <key> } }, number: { in: [...nums] } } ← identifiers
+ *                                                                  grouped by team
+ * Linear returns nodes in DB order, NOT input order — the caller is
+ * responsible for re-sorting to match the input list before surfacing.
+ *
+ * `$first` is `refCount * 2`, clamped to [100, 250] — the floor absorbs the
+ * rare case where Linear returns more rows than requested via OR-clause
+ * collisions; the ceiling is Linear's connection-page cap, beyond which the
+ * server silently truncates.
+ *
+ * Raw GraphQL (not @linear/sdk) is required because the SDK's
+ * `client.issues({ filter: ... })` strips through the same query under
+ * the hood but forces one round-trip per call site; the doctrine in
+ * CLAUDE.md ("Performance-critical loops where the SDK's per-edge
+ * resolver promises produce N+1 round-trips") explicitly authorizes this.
+ */
+export const BATCH_GET_ISSUES_QUERY = `
+  query BatchGetIssues($filter: IssueFilter!, $first: Int!) {
+    issues(filter: $filter, first: $first) {
+      nodes {
+        ${COMPLETE_ISSUE_WITH_COMMENTS_FRAGMENT}
+      }
+    }
+  }
+`;
 /**
  * Batch-resolves an update's project/milestone/issue inputs.
  *

package/dist/queries/project-milestones.d.ts

@@ -1,5 +1,5 @@
 export declare const LIST_PROJECT_MILESTONES_QUERY = "\n  query ListProjectMilestones($projectId: String!, $first: Int!) {\n    project(id: $projectId) {\n      id\n      name\n      projectMilestones(first: $first) {\n        nodes {\n          id\n          name\n          description\n          targetDate\n          sortOrder\n          createdAt\n          updatedAt\n        }\n      }\n    }\n  }\n";
-export declare const GET_PROJECT_MILESTONE_BY_ID_QUERY = "\n  query GetProjectMilestone($id: String!, $issuesFirst: Int) {\n    projectMilestone(id: $id) {\n      id\n      name\n      description\n      targetDate\n      sortOrder\n      createdAt\n      updatedAt\n      project {\n        id\n        name\n      }\n      issues(first: $issuesFirst) {\n        nodes {\n          \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n        }\n      }\n    }\n  }\n";
+export declare const GET_PROJECT_MILESTONE_BY_ID_QUERY = "\n  query GetProjectMilestone($id: String!, $issuesFirst: Int) {\n    projectMilestone(id: $id) {\n      id\n      name\n      description\n      targetDate\n      sortOrder\n      createdAt\n      updatedAt\n      project {\n        id\n        name\n      }\n      issues(first: $issuesFirst) {\n        nodes {\n          \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n        }\n      }\n    }\n  }\n";
 export declare const FIND_PROJECT_MILESTONE_BY_NAME_SCOPED = "\n  query FindProjectMilestoneScoped($name: String!, $projectId: String!) {\n    project(id: $projectId) {\n      projectMilestones(filter: { name: { eq: $name } }, first: 10) {\n        nodes {\n          id\n          name\n          targetDate\n          sortOrder\n          project {\n            id\n            name\n          }\n        }\n      }\n    }\n  }\n";
 export declare const FIND_PROJECT_MILESTONE_BY_NAME_GLOBAL = "\n  query FindProjectMilestoneGlobal($name: String!) {\n    projectMilestones(filter: { name: { eq: $name } }, first: 10) {\n      nodes {\n        id\n        name\n        targetDate\n        sortOrder\n        project {\n          id\n          name\n        }\n      }\n    }\n  }\n";
 export declare const CREATE_PROJECT_MILESTONE_MUTATION = "\n  mutation CreateProjectMilestone($projectId: String!, $name: String!, $description: String, $targetDate: TimelessDate) {\n    projectMilestoneCreate(input: {\n      projectId: $projectId\n      name: $name\n      description: $description\n      targetDate: $targetDate\n    }) {\n      success\n      projectMilestone {\n        id\n        name\n        description\n        targetDate\n        sortOrder\n        createdAt\n        updatedAt\n        project {\n          id\n          name\n        }\n      }\n    }\n  }\n";

package/dist/types/linear.d.ts

@@ -27,6 +27,13 @@ interface UserRef {
 interface StateRef {
     id: string;
     name: string;
+    /**
+     * Linear workflow-state type: `triage` / `backlog` / `unstarted` /
+     * `started` / `completed` / `canceled`. Optional because pre-DEV-4478
+     * callers and some legacy GraphQL selections didn't request it; new
+     * code (default state-filtering, e.g.) should set it.
+     */
+    type?: string;
 }
 interface ProjectRef {
     id: string;

package/dist/utils/extract-field.d.ts

@@ -16,4 +16,20 @@
  * Returns `null` when the field isn't found, so callers can distinguish
  * "missing" from "empty body".
  */
+/**
+ * Multi-section variant of `extractField`. Extracts each requested section
+ * by name in one call and returns a `{section -> text|null}` map preserving
+ * the caller's order. Missing sections map to `null` so the caller can
+ * distinguish "absent" from "empty" the same way `extractField` does.
+ *
+ * Each name is matched independently via `extractField` — semantics are
+ * identical (first-match wins, case-insensitive, fenced-code-block aware).
+ *
+ * DEV-4479: this is the primitive behind `el-linear issues read --sections
+ * "Done when,Out of scope"` so agents can pull several sections in one
+ * call instead of N spawns. (The CLI flag landed as `--sections` rather
+ * than `--fields` because `--fields` is already the program-level
+ * output-key filter — see the option's `addHelpText` for context.)
+ */
+export declare function extractFields(body: string, fieldNames: readonly string[]): Map<string, string | null>;
 export declare function extractField(body: string, fieldName: string): string | null;

package/dist/utils/extract-field.js

@@ -59,6 +59,28 @@ function matchHeader(line) {
     }
     return null;
 }
+/**
+ * Multi-section variant of `extractField`. Extracts each requested section
+ * by name in one call and returns a `{section -> text|null}` map preserving
+ * the caller's order. Missing sections map to `null` so the caller can
+ * distinguish "absent" from "empty" the same way `extractField` does.
+ *
+ * Each name is matched independently via `extractField` — semantics are
+ * identical (first-match wins, case-insensitive, fenced-code-block aware).
+ *
+ * DEV-4479: this is the primitive behind `el-linear issues read --sections
+ * "Done when,Out of scope"` so agents can pull several sections in one
+ * call instead of N spawns. (The CLI flag landed as `--sections` rather
+ * than `--fields` because `--fields` is already the program-level
+ * output-key filter — see the option's `addHelpText` for context.)
+ */
+export function extractFields(body, fieldNames) {
+    const out = new Map();
+    for (const name of fieldNames) {
+        out.set(name, extractField(body, name));
+    }
+    return out;
+}
 export function extractField(body, fieldName) {
     if (!body)
         return null;

package/dist/utils/format-tree.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ASCII tree formatter for `issues tree <ID>` (DEV-4480).
+ *
+ * Renders a parent → children tree using the same box-drawing prefixes as
+ * the standard `tree` Unix utility (`├── `, `└── `, `│   `, `    `). Each
+ * line is `<prefix> <identifier> <title> <state-suffix>`, where the
+ * state-suffix is `[Done]` / `[Canceled]` for terminal-typed states and
+ * omitted otherwise.
+ *
+ * Pure rendering — does not fetch or filter. The depth bound and the
+ * terminal-state exclusion are enforced by the caller before this runs.
+ */
+import type { IssueTreeNode } from "../queries/issue-tree.js";
+export declare function formatTree(root: IssueTreeNode): string;

package/dist/utils/format-tree.js

@@ -0,0 +1,47 @@
+/**
+ * ASCII tree formatter for `issues tree <ID>` (DEV-4480).
+ *
+ * Renders a parent → children tree using the same box-drawing prefixes as
+ * the standard `tree` Unix utility (`├── `, `└── `, `│   `, `    `). Each
+ * line is `<prefix> <identifier> <title> <state-suffix>`, where the
+ * state-suffix is `[Done]` / `[Canceled]` for terminal-typed states and
+ * omitted otherwise.
+ *
+ * Pure rendering — does not fetch or filter. The depth bound and the
+ * terminal-state exclusion are enforced by the caller before this runs.
+ */
+const BRANCH_TEE = "├── ";
+const BRANCH_END = "└── ";
+const VERTICAL = "│   ";
+const SPACE = "    ";
+export function formatTree(root) {
+    const lines = [formatNode(root)];
+    const kids = root.children?.nodes ?? [];
+    for (let i = 0; i < kids.length; i++) {
+        appendSubtree(lines, kids[i], "", i === kids.length - 1);
+    }
+    return lines.join("\n");
+}
+function appendSubtree(lines, node, prefix, isLast) {
+    const branch = isLast ? BRANCH_END : BRANCH_TEE;
+    lines.push(`${prefix}${branch}${formatNode(node)}`);
+    const childPrefix = prefix + (isLast ? SPACE : VERTICAL);
+    const kids = node.children?.nodes ?? [];
+    for (let i = 0; i < kids.length; i++) {
+        appendSubtree(lines, kids[i], childPrefix, i === kids.length - 1);
+    }
+}
+function formatNode(node) {
+    const stateSuffix = node.state ? formatStateSuffix(node.state) : "";
+    const assigneeSuffix = node.assignee ? ` (@${node.assignee.name})` : "";
+    return `${node.identifier} ${node.title}${stateSuffix}${assigneeSuffix}`;
+}
+function formatStateSuffix(state) {
+    // Only annotate terminal-typed states; the renderer is otherwise
+    // state-name-agnostic so workspace-custom workflow states (e.g. "In
+    // Review") don't get a noisy suffix.
+    if (state.type === "completed" || state.type === "canceled") {
+        return ` [${state.name}]`;
+    }
+    return "";
+}

package/dist/utils/graphql-issues-service.d.ts

@@ -41,6 +41,14 @@ export interface SearchIssueArgs {
     delegateId?: string;
     /** Issue states to include (e.g. `["Todo", "In Progress"]`). */
     status?: string[];
+    /**
+     * Exclude terminal states (workflow type `completed` or `canceled`).
+     * Default `false` for back-compat at the service layer; the CLI's
+     * `issues list` / `issues search` flip this to `true` by default
+     * (DEV-4478) and accept `--include-closed` to opt back in. When
+     * `status` is also set, this is ignored — explicit user choice wins.
+     */
+    excludeTerminalStates?: boolean;
     /** Label names to require (intersection). */
     labelNames?: string[];
     /** Priority values (0-4) to include. */
@@ -149,6 +157,24 @@ export declare class GraphQLIssuesService {
     constructor(graphQLService: GraphQLService, linearService: LinearService);
     getIssues(limit?: number): Promise<LinearIssue[]>;
     getIssueById(issueId: string): Promise<LinearIssue>;
+    /**
+     * Batch-fetches N issues in a single GraphQL round-trip (DEV-4477).
+     *
+     * Replaces `Promise.all(refs.map(getIssueById))` — that pattern issues N
+     * concurrent queries; this one issues exactly one. Useful for
+     * `el-linear issues read <id...>`, the only caller today.
+     *
+     * Identifier shapes accepted (mirrors `getIssueById`):
+     *   - UUIDs (`isUuid(ref)` matches) — batched into a single `id.in` clause.
+     *   - `TEAM-N` identifiers (`parseIssueIdentifier(ref)` matches) — grouped
+     *     by team key into one `{ team.key.eq, number.in }` clause per team.
+     *
+     * Linear returns nodes in DB order; this method re-sorts to match the
+     * input list and throws `notFoundError` if any ref did not resolve, with
+     * the first missing ref named in the error. Order-preservation matters
+     * for the read handler — the JSON envelope is a positional array.
+     */
+    getIssuesByRefs(refs: string[]): Promise<LinearIssue[]>;
     startIssue(issueId: string): Promise<StartIssueResult>;
     updateIssue(args: UpdateIssueArgs, labelMode?: string): Promise<LinearIssue>;
     archiveIssue(issueId: string): Promise<IssueArchiveOperationResult>;

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

@@ -1,5 +1,5 @@
 import { resolveUserDisplayName } from "../config/resolver.js";
-import { ARCHIVE_ISSUE_MUTATION, BATCH_RESOLVE_FOR_CREATE_QUERY, BATCH_RESOLVE_FOR_SEARCH_QUERY, BATCH_RESOLVE_FOR_UPDATE_QUERY, buildResolveLabelsByNameQuery, CREATE_ISSUE_MUTATION, DELETE_ISSUE_MUTATION, FILTERED_SEARCH_ISSUES_QUERY, GET_ISSUE_BY_ID_QUERY, GET_ISSUE_BY_IDENTIFIER_QUERY, GET_ISSUE_START_CONTEXT_QUERY, GET_ISSUE_TEAM_QUERY, GET_ISSUES_QUERY, SEARCH_ISSUES_QUERY, TEAM_STARTED_STATUSES_QUERY, UPDATE_ISSUE_MUTATION, } from "../queries/issues.js";
+import { ARCHIVE_ISSUE_MUTATION, BATCH_GET_ISSUES_QUERY, BATCH_RESOLVE_FOR_CREATE_QUERY, BATCH_RESOLVE_FOR_SEARCH_QUERY, BATCH_RESOLVE_FOR_UPDATE_QUERY, buildResolveLabelsByNameQuery, CREATE_ISSUE_MUTATION, DELETE_ISSUE_MUTATION, FILTERED_SEARCH_ISSUES_QUERY, GET_ISSUE_BY_ID_QUERY, GET_ISSUE_BY_IDENTIFIER_QUERY, GET_ISSUE_START_CONTEXT_QUERY, GET_ISSUE_TEAM_QUERY, GET_ISSUES_QUERY, SEARCH_ISSUES_QUERY, TEAM_STARTED_STATUSES_QUERY, UPDATE_ISSUE_MUTATION, } from "../queries/issues.js";
 import { CREATE_LABEL_MUTATION } from "../queries/labels.js";
 import { toISOStringOrNow } from "./date-format.js";
 import { extractEmbeds } from "./embed-parser.js";
@@ -61,6 +61,95 @@ export class GraphQLIssuesService {
         }
         return this.transformIssueData(issueData);
     }
+    /**
+     * Batch-fetches N issues in a single GraphQL round-trip (DEV-4477).
+     *
+     * Replaces `Promise.all(refs.map(getIssueById))` — that pattern issues N
+     * concurrent queries; this one issues exactly one. Useful for
+     * `el-linear issues read <id...>`, the only caller today.
+     *
+     * Identifier shapes accepted (mirrors `getIssueById`):
+     *   - UUIDs (`isUuid(ref)` matches) — batched into a single `id.in` clause.
+     *   - `TEAM-N` identifiers (`parseIssueIdentifier(ref)` matches) — grouped
+     *     by team key into one `{ team.key.eq, number.in }` clause per team.
+     *
+     * Linear returns nodes in DB order; this method re-sorts to match the
+     * input list and throws `notFoundError` if any ref did not resolve, with
+     * the first missing ref named in the error. Order-preservation matters
+     * for the read handler — the JSON envelope is a positional array.
+     */
+    async getIssuesByRefs(refs) {
+        if (refs.length === 0) {
+            return [];
+        }
+        if (refs.length === 1) {
+            // Single ref → fall through to the single-issue path, which has
+            // the right error semantics (notFoundError on miss) and avoids
+            // building an OR clause with one branch.
+            return [await this.getIssueById(refs[0])];
+        }
+        const uuids = [];
+        const byTeam = new Map();
+        for (const ref of refs) {
+            if (isUuid(ref)) {
+                uuids.push(ref);
+                continue;
+            }
+            const { teamKey, issueNumber } = parseIssueIdentifier(ref);
+            const existing = byTeam.get(teamKey);
+            if (existing) {
+                existing.push(issueNumber);
+            }
+            else {
+                byTeam.set(teamKey, [issueNumber]);
+            }
+        }
+        const orClauses = [];
+        if (uuids.length > 0) {
+            orClauses.push({ id: { in: uuids } });
+        }
+        for (const [teamKey, numbers] of byTeam) {
+            orClauses.push({
+                team: { key: { eq: teamKey } },
+                number: { in: numbers },
+            });
+        }
+        // `first` is sized at 2x refs.length to absorb the rare case where
+        // Linear returns extra rows from the OR clauses (e.g. a typo-collision
+        // across teams). Floor of 100 covers small batches comfortably; ceiling
+        // of 250 is Linear's connection cap — exceeding it would silently
+        // truncate and we'd `notFoundError` on the truncated refs. With the
+        // ceiling clamped, a >125-ref batch would risk under-fetching, but
+        // `read <id...>` is typed-by-hand and never approaches that scale.
+        // (Cycle-1 nit.)
+        const first = Math.min(Math.max(refs.length * 2, 100), 250);
+        const result = await this.graphQLService.rawRequest(BATCH_GET_ISSUES_QUERY, { filter: { or: orClauses }, first });
+        const nodes = result.issues?.nodes ?? [];
+        // Build an index for O(1) per-ref lookup, then re-emit in input order.
+        // A node is reachable by both its UUID and its identifier; both index
+        // keys point at the same node object. This is intentional: if a caller
+        // passes both forms for the same issue (`["xxxxxx-...", "DEV-1"]`),
+        // or the same ref twice (`["DEV-1", "DEV-1"]`), each input ref gets
+        // its own output entry — the contract is "output shape mirrors input
+        // shape", not "dedupe by underlying issue". (Cycle-1 nit.)
+        const byUuid = new Map();
+        const byIdentifier = new Map();
+        for (const node of nodes) {
+            byUuid.set(node.id, node);
+            if (node.identifier) {
+                byIdentifier.set(node.identifier, node);
+            }
+        }
+        const ordered = [];
+        for (const ref of refs) {
+            const node = isUuid(ref) ? byUuid.get(ref) : byIdentifier.get(ref);
+            if (!node) {
+                throw notFoundError("Issue", ref);
+            }
+            ordered.push(node);
+        }
+        return ordered.map((issue) => this.transformIssueData(issue));
+    }
     async startIssue(issueId) {
         const resolvedIssueId = await this.linearService.resolveIssueId(issueId);
         const context = await this.graphQLService.rawRequest(GET_ISSUE_START_CONTEXT_QUERY, { id: resolvedIssueId });
@@ -391,6 +480,7 @@ export class GraphQLIssuesService {
                 delegateId: finalDelegateId,
                 project: projectFilter,
                 status: args.status,
+                excludeTerminalStates: args.excludeTerminalStates,
                 labelNames: args.labelNames,
                 priority: args.priority,
             });
@@ -401,6 +491,7 @@ export class GraphQLIssuesService {
             delegateId: finalDelegateId,
             project: projectFilter,
             status: args.status,
+            excludeTerminalStates: args.excludeTerminalStates,
             labelNames: args.labelNames,
             priority: args.priority,
         });
@@ -820,6 +911,11 @@ export class GraphQLIssuesService {
         if (filters.status && filters.status.length > 0) {
             filtered = filtered.filter((issue) => filters.status.includes(issue.state?.name ?? ""));
         }
+        else if (filters.excludeTerminalStates) {
+            // Implicit terminal-state exclusion (DEV-4478). Explicit `status`
+            // always wins — the user already named the states they want.
+            filtered = filtered.filter((issue) => issue.state?.type !== "completed" && issue.state?.type !== "canceled");
+        }
         if (filters.labelNames && filters.labelNames.length > 0) {
             const lowerNames = filters.labelNames.map((n) => n.toLowerCase());
             filtered = filtered.filter((issue) => {
@@ -858,6 +954,11 @@ export class GraphQLIssuesService {
         if (filters.status && filters.status.length > 0) {
             filter.state = { name: { in: filters.status } };
         }
+        else if (filters.excludeTerminalStates) {
+            // Implicit terminal-state exclusion (DEV-4478). Explicit `status`
+            // always wins — the user already named the states they want.
+            filter.state = { type: { nin: ["completed", "canceled"] } };
+        }
         if (filters.labelNames && filters.labelNames.length > 0) {
             if (filters.labelNames.length === 1) {
                 filter.labels = {
@@ -1097,7 +1198,13 @@ export class GraphQLIssuesService {
     transformIssueRelations(issue) {
         return {
             state: issue.state
-                ? { id: issue.state.id, name: issue.state.name }
+                ? {
+                    id: issue.state.id,
+                    name: issue.state.name,
+                    // DEV-4478: surface workflow-state `type` so callers can filter
+                    // terminal states (`completed`, `canceled`) without re-querying.
+                    type: issue.state.type,
+                }
                 : undefined,
             assignee: issue.assignee
                 ? {

package/dist/utils/with-includes.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `issues read --with` parser (DEV-4476).
+ *
+ * Opt-in includes for `issues read`. Each value names an additional block
+ * of data to fetch alongside the base issue and inject into the JSON
+ * envelope. Comma-separated; whitespace tolerated; unknown values rejected
+ * with a structured error naming the candidates (deterministic-CLI
+ * doctrine — fail fast in the CLI, not in the consumer's script).
+ *
+ * Currently supported:
+ *   - `relations` — fetches `Issue.relations` + `Issue.inverseRelations`
+ *                   and adds a `relations` array to the envelope.
+ *
+ * Reserved for future MRs (the value space is a closed set so adding more
+ * later is back-compat):
+ *   - `children`  — refetch with expanded sub-issue fragment (state,
+ *                   assignee, priority — beyond the default id/identifier/
+ *                   title trio that's already in the envelope).
+ *   - `comments`  — no-op for fetching (comments are already in the
+ *                   default envelope via `_WITH_COMMENTS` fragment) but
+ *                   would gate explicit summary-format rendering.
+ *
+ * Doctrine note: comments are intentionally NOT included today because
+ * adding `--with comments` would imply that comments are *off* by default,
+ * which would be a breaking JSON-shape change.
+ */
+export declare const WITH_INCLUDE_VALUES: readonly ["relations"];
+export type WithInclude = (typeof WITH_INCLUDE_VALUES)[number];
+export interface ParsedWithIncludes {
+    relations: boolean;
+}
+/**
+ * Parse a `--with <names>` argument. Returns a flag object so call sites
+ * read `if (includes.relations)` instead of `Set.has("relations")`.
+ *
+ * Empty / whitespace-only values are caller errors (commander allows
+ * `--with ""` through) — reject with the same message as unknown values
+ * so the user gets one consistent failure mode.
+ */
+export declare function parseWithIncludes(raw: string): ParsedWithIncludes;