@enrichlayer/el-linear 1.19.0 → 1.20.0

package/README.md

@@ -447,6 +447,24 @@ el-linear <command> --help       # detailed help for one command
 All `list` subcommands support `-l, --limit <n>`. All commands accept the
 top-level filters: `--format <json|summary>`, `--raw`, `--jq <expr>`, `--fields <list>`.
 
+### Open by default — `issues list` and `issues search` skip terminal states
+
+`el-linear issues list` and `el-linear issues search` **exclude issues in
+terminal workflow states (`Done` / `Canceled`) by default** so triage and
+survey runs return the open set without piping through `grep`. The implicit
+filter is surfaced in `_warnings` on every invocation, so scripts notice it
+deterministically rather than silently. Three ways to opt back in:
+
+```bash
+el-linear issues list --include-closed              # everything, including Done/Canceled
+el-linear issues search "auth" --status "Done"      # explicit --status wins
+el-linear issues list --status "Todo,In Progress"   # any explicit status disables the implicit filter
+```
+
+`--include-closed` and explicit `--status` both bypass the implicit filter
+(explicit choice always wins). The change is per-command and only affects
+list-shaped reads — single-issue `issues read DEV-123` is unaffected.
+
 ## Output formats
 
 Every command accepts `--format <kind>` at the root:
@@ -535,6 +553,52 @@ el-linear read ADM-652 --field "Out of scope"
 Single-issue only — pair it with `--jq` on full JSON for batch
 extraction across many issues.
 
+### Render an issue's tree: `issues tree`
+
+`issues tree <ID>` walks the parent → children graph for an issue in a
+single GraphQL round-trip and returns either a nested JSON envelope
+(default) or an ASCII tree (`--format summary`).
+
+```bash
+el-linear issues tree DEV-100 --format summary
+# DEV-100 Migrate auth middleware
+# ├── DEV-101 Write design doc
+# │   ├── DEV-104 Survey existing auth flows [Done]
+# │   └── DEV-105 Draft RFC
+# ├── DEV-102 Build new session store (@Alice)
+# └── DEV-103 Cutover plan
+```
+
+Depth defaults to **3** (max 5 — Linear has no native depth-N recursion,
+so each level adds a `children { nodes { ... } }` block to the generated
+query). Terminal-state branches (`Done` / `Canceled`) are **kept** by
+default because the tree's value is *structural*; pass
+`--no-include-closed` to prune them.
+
+### Extract several sections in one call: `--sections`
+
+When you want multiple sections (e.g. `Done when`, `Out of scope`, and
+`Steps`), don't issue N separate `--field` calls — pass a comma-separated
+list to `--sections` instead:
+
+```bash
+el-linear issues read DEV-123 --sections "Done when,Out of scope"
+# {
+#   "identifier": "DEV-123",
+#   "sections": {
+#     "Done when": "...",
+#     "Out of scope": "..."
+#   }
+# }
+```
+
+Returns a JSON envelope `{ identifier, sections: { name → text|null } }`.
+Missing sections map to `null` and surface in `_warnings` so scripts can
+detect them deterministically. Single-issue only, mutually exclusive
+with `--field`. (Named `--sections` rather than the seemingly-obvious
+`--fields` because `--fields` is already taken at the program level for
+output-key filtering — `el-linear` is the namespace owner.)
+
 ## Wrapping Linear references in arbitrary text
 
 `el-linear refs wrap` takes plain text on stdin (or via `--file`) and rewrites

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

@@ -123,7 +123,11 @@ and outreach tracked in one place.
 **Search before creating. No exceptions.**
 
 ```bash
-el-linear issues search "keywords from proposed title" 2>&1
+# --include-closed is required so previously-completed duplicates surface.
+# `issues search` defaults to open states (DEV-4478); the duplicate check
+# intentionally widens to Done/Canceled because a closed-out duplicate is
+# still a duplicate.
+el-linear issues search "keywords from proposed title" --include-closed 2>&1
 ```
 
 1. Extract 2–3 key terms from the proposed title (skip generic words).
@@ -269,6 +273,7 @@ Run `el-linear usage` for the full command reference. Non-obvious rules:
 - **Subcommand aliases** — `read`/`view`/`get`/`show`, `update`/`edit`/`set`.
 - **`--jq` for GraphQL filtering** — never pipe through `jq` directly (zsh escaping breaks `!=`).
 - **`--raw` flag** strips the `{ data, meta }` wrapper — emits just the array.
+- **Body/description from a file** — `issues create`/`update` take `--description-file <path>`; `comments create`/`update` take `--body-file <path>`. Prefer the file form for any body with backticks, fenced code, or markdown tables — it sidesteps shell-quoting traps (the same reason `el-git mr comment --body-file` exists). `--body` and `--body-file` are **mutually exclusive** (passing both errors); file-sourced bodies get the same auto-link / auto-mention treatment as inline `--body`.
 
 ### Output format
 

package/dist/commands/comments.js

@@ -18,6 +18,12 @@ import { getWorkspaceUrlKey } from "../utils/workspace-url.js";
 const BODY_DATA_ERROR_RE = /prosemirror|bodydata|invalid.*body/i;
 const ISSUE_IDENTIFIER_REGEX = /^[A-Z][A-Z0-9]*-\d+$/;
 function readBody(options) {
+    // --body and --body-file are two sources for the same field; accepting both
+    // would silently drop one. Reject up front (DEV-4450) — the same mutual-
+    // exclusivity contract resolveDescription() enforces for --template.
+    if (options.body && options.bodyFile) {
+        throw new Error("--body and --body-file are mutually exclusive — pass one or the other");
+    }
     if (options.bodyFile) {
         return readFileSync(options.bodyFile, "utf-8");
     }

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

@@ -0,0 +1,22 @@
+/**
+ * `el-linear issues tree <ID>` (DEV-4480).
+ *
+ * Renders the parent-and-children tree of an issue to depth N (default 3,
+ * max 5 — see `MAX_TREE_DEPTH`). One GraphQL round-trip per invocation;
+ * the query string is generated by `buildIssueTreeQuery(depth)` at call
+ * time because the children connection has no `@include`-style depth
+ * directive.
+ *
+ * Two output modes:
+ *   - **JSON** (default): nested `IssueTreeNode` shape.
+ *   - **Summary**: ASCII tree via `formatTree`.
+ *
+ * Closed-issue filtering: `--include-closed` is on by default for `tree`
+ * because the tree's value is *structural* — knowing that a child was
+ * canceled is part of the picture. Pass `--no-include-closed` to prune
+ * terminal-state branches client-side after the fetch (Linear's children
+ * connection has no top-level state filter).
+ */
+import type { Command, OptionValues } from "commander";
+export declare function setupTreeCommand(issues: Command): void;
+export declare function handleTreeCommand(issueId: string, options: OptionValues, command: Command): Promise<void>;

package/dist/commands/issues/tree.js

@@ -0,0 +1,102 @@
+/**
+ * `el-linear issues tree <ID>` (DEV-4480).
+ *
+ * Renders the parent-and-children tree of an issue to depth N (default 3,
+ * max 5 — see `MAX_TREE_DEPTH`). One GraphQL round-trip per invocation;
+ * the query string is generated by `buildIssueTreeQuery(depth)` at call
+ * time because the children connection has no `@include`-style depth
+ * directive.
+ *
+ * Two output modes:
+ *   - **JSON** (default): nested `IssueTreeNode` shape.
+ *   - **Summary**: ASCII tree via `formatTree`.
+ *
+ * Closed-issue filtering: `--include-closed` is on by default for `tree`
+ * because the tree's value is *structural* — knowing that a child was
+ * canceled is part of the picture. Pass `--no-include-closed` to prune
+ * terminal-state branches client-side after the fetch (Linear's children
+ * connection has no top-level state filter).
+ */
+import { buildIssueTreeQuery, DEFAULT_TREE_DEPTH, MAX_TREE_DEPTH, } from "../../queries/issue-tree.js";
+import { formatTree } from "../../utils/format-tree.js";
+import { createIssuesService } from "../../utils/issues-service-bootstrap.js";
+import { handleAsyncCommand, outputSuccess } from "../../utils/output.js";
+import { getRootOpts } from "../../utils/root-opts.js";
+export function setupTreeCommand(issues) {
+    issues
+        .command("tree <issueId>")
+        .description("Render the parent-and-children tree of an issue (DEV-4480). " +
+        "One GraphQL call. Depth defaults to 3 (max 5).")
+        .option("--depth <n>", `Tree depth, integer in [1, ${MAX_TREE_DEPTH}] (default ${DEFAULT_TREE_DEPTH})`, String(DEFAULT_TREE_DEPTH))
+        .option("--no-include-closed", "Prune branches whose state is Done or Canceled. By default tree " +
+        "renders all states because the tree's value is structural.")
+        .addHelpText("after", "\nExamples:" +
+        "\n  el-linear issues tree DEV-100" +
+        "\n  el-linear issues tree DEV-100 --depth 5 --format summary" +
+        "\n  el-linear issues tree DEV-100 --no-include-closed")
+        .action(handleAsyncCommand(handleTreeCommand));
+}
+export async function handleTreeCommand(issueId, options, command) {
+    const rootOpts = getRootOpts(command);
+    const { graphQLService, linearService } = await createIssuesService(rootOpts);
+    const treeOptions = options;
+    const depth = parseDepth(treeOptions.depth);
+    // commander turns `--no-include-closed` into `includeClosed: false`; the
+    // default is true (see option declaration).
+    const includeClosed = treeOptions.includeClosed !== false;
+    const resolvedId = await linearService.resolveIssueId(issueId);
+    const result = await graphQLService.rawRequest(buildIssueTreeQuery(depth), { id: resolvedId });
+    if (!result.issue) {
+        throw new Error(`Issue "${issueId}" not found`);
+    }
+    const filtered = includeClosed
+        ? result.issue
+        : pruneTerminalStates(result.issue);
+    // `--format` is a *root-program* option (see main.ts), so commander
+    // surfaces it via `command.parent.opts()` — NOT via the subcommand
+    // action's local `options` parameter. Reading from `rootOpts` mirrors
+    // the precedent in `read-shortcut.ts`'s `--field` handling.
+    // (DEV-4480 cycle-1 blocker.)
+    if (rootOpts.format === "summary") {
+        process.stdout.write(`${formatTree(filtered)}\n`);
+        return;
+    }
+    outputSuccess(filtered);
+}
+function parseDepth(raw) {
+    if (raw === undefined) {
+        return DEFAULT_TREE_DEPTH;
+    }
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isInteger(n) || n < 1 || n > MAX_TREE_DEPTH) {
+        throw new Error(`--depth must be an integer in [1, ${MAX_TREE_DEPTH}]; got "${raw}".`);
+    }
+    return n;
+}
+/**
+ * Walk the tree depth-first and drop any node whose `state.type` is
+ * `completed` or `canceled`. Pure function — does not mutate the input.
+ * A pruned child takes its entire subtree with it (consistent with how
+ * `issues list --no-include-closed` excludes closed work entirely).
+ *
+ * Assumes Linear's parent → children graph stays single-parent (a tree,
+ * not a DAG). If Linear ever ships multi-parent issues, this recursion
+ * would re-emit nodes reachable via multiple paths — at that point add
+ * a `Set<string>` of seen `id`s to the walk. Today the assumption is
+ * safe. Bounded recursion: `MAX_TREE_DEPTH=5` caps the call stack at
+ * ≤6 frames (root + 5 children levels). (Cycle-1 nit.)
+ */
+function pruneTerminalStates(root) {
+    const kids = root.children?.nodes ?? [];
+    const surviving = kids
+        .filter((c) => !isTerminalState(c))
+        .map((c) => pruneTerminalStates(c));
+    return {
+        ...root,
+        children: { nodes: surviving },
+    };
+}
+function isTerminalState(node) {
+    const t = node.state?.type;
+    return t === "completed" || t === "canceled";
+}

package/dist/commands/issues.js

@@ -21,6 +21,7 @@ import { currentGitBranch, extractIssueIdentifierFromBranch, getBranchLinearIssu
 import { maybeAutoLink, prepareAutoLinkedDescription, readDescriptionFile, resolveDescription, } from "./issues/description.js";
 import { handleLinkReferencesIssue } from "./issues/link-references.js";
 import { buildIncomingRelationEntries, buildOutgoingRelationEntries, createRelations, } from "./issues/relations.js";
+import { setupTreeCommand } from "./issues/tree.js";
 import { readIssues } from "./read-shortcut.js";
 const IMAGE_EXTENSIONS = new Set([
     ".png",
@@ -160,7 +161,12 @@ async function handleListIssues(options, command) {
     }
     const rootOpts = getRootOpts(command);
     const { issuesService } = await createIssuesService(rootOpts);
-    const hasFilters = options.team ||
+    const explicitStatus = options.status ? splitList(options.status) : undefined;
+    // DEV-4478: default-exclude terminal states (Done/Canceled) unless the
+    // user passes --include-closed OR explicit --status. Explicit status
+    // wins because the user already named the workflow states they want.
+    const excludeTerminalStates = !options.includeClosed && explicitStatus === undefined;
+    const hasOtherFilters = options.team ||
         options.labels ||
         options.status ||
         options.assignee ||
@@ -169,7 +175,14 @@ async function handleListIssues(options, command) {
         options.project === false ||
         options.priority;
     const limit = parsePositiveInt(options.limit, "--limit");
-    if (hasFilters) {
+    // Route through searchIssues whenever the CLI needs to control the GraphQL
+    // state filter: any explicit filter, the default `excludeTerminalStates`,
+    // OR an explicit `--include-closed`. The last case is load-bearing —
+    // getIssues' query hard-codes `state: { type: { neq: "completed" } }`, so
+    // falling through to it on `--include-closed --no-other-filters` would
+    // silently drop Done issues, the exact opposite of the flag's intent.
+    // (DEV-4478 cycle-1.)
+    if (hasOtherFilters || excludeTerminalStates || options.includeClosed) {
         const searchArgs = {
             teamId: options.team ? resolveTeam(options.team) : undefined,
             assigneeId: options.assignee
@@ -180,7 +193,8 @@ async function handleListIssues(options, command) {
                 : undefined,
             project: resolveProjectFlag(options.project),
             labelNames: options.labels ? splitList(options.labels) : undefined,
-            status: options.status ? splitList(options.status) : undefined,
+            status: explicitStatus,
+            excludeTerminalStates,
             priority: options.priority
                 ? parsePriorityFilter(options.priority)
                 : undefined,
@@ -188,6 +202,9 @@ async function handleListIssues(options, command) {
             limit,
         };
         const result = sortIssues(await issuesService.searchIssues(searchArgs), options.sort);
+        if (excludeTerminalStates) {
+            outputWarning("excluded terminal states (Done / Canceled) by default; pass --include-closed to include them");
+        }
         warnIfTruncated(result.length, limit);
         outputIssues(result, options.format, options.fields, {
             team: options.team,
@@ -206,6 +223,11 @@ async function handleSearchIssues(query, options, command) {
     const rootOpts = getRootOpts(command);
     const { issuesService } = await createIssuesService(rootOpts);
     const limit = parsePositiveInt(options.limit, "--limit");
+    const explicitStatus = options.status ? splitList(options.status) : undefined;
+    // DEV-4478: default-exclude terminal states (Done/Canceled) unless the
+    // user passes --include-closed OR explicit --status. Explicit status
+    // wins because the user already named the workflow states they want.
+    const excludeTerminalStates = !options.includeClosed && explicitStatus === undefined;
     const searchArgs = {
         query,
         teamId: options.team ? resolveTeam(options.team) : undefined,
@@ -216,7 +238,8 @@ async function handleSearchIssues(query, options, command) {
             ? resolveMember(options.delegate)
             : undefined,
         project: resolveProjectFlag(options.project),
-        status: options.status ? splitList(options.status) : undefined,
+        status: explicitStatus,
+        excludeTerminalStates,
         labelNames: options.labels ? splitList(options.labels) : undefined,
         priority: options.priority
             ? parsePriorityFilter(options.priority)
@@ -224,6 +247,9 @@ async function handleSearchIssues(query, options, command) {
         limit,
     };
     const result = sortIssues(await issuesService.searchIssues(searchArgs), options.sort);
+    if (excludeTerminalStates) {
+        outputWarning("excluded terminal states (Done / Canceled) by default; pass --include-closed to include them");
+    }
     warnIfTruncated(result.length, limit);
     outputIssues(result, options.format, options.fields, { query });
 }
@@ -869,6 +895,10 @@ export function setupIssuesCommands(program) {
         .alias("issue")
         .description("Issue operations");
     issues.action(() => issues.help());
+    // DEV-4480: `issues tree <ID>` lives in its own file because the
+    // recursive query builder + ASCII formatter belong together and are
+    // substantial enough to warrant the split.
+    setupTreeCommand(issues);
     issues
         .command("list")
         .description("List issues.")
@@ -881,6 +911,7 @@ export function setupIssuesCommands(program) {
         .option("--labels <labels>", "filter by labels (comma-separated names)")
         .option("--label <labels>", "alias for --labels")
         .option("--status <status>", "filter by status (comma-separated, e.g. Todo,Backlog)")
+        .option("--include-closed", "include issues in terminal states (Done / Canceled). Default is to exclude them; pass this flag to see everything. Ignored when --status is set (explicit choice wins).")
         .option("--priority <priority>", "filter by priority (comma-separated: urgent,high,medium,low,none or 0-4)")
         .option("--sort <field>", "sort results (priority, status, created, updated)")
         .option("--format <format>", "output format (json, summary, table, md, csv)", "json")
@@ -895,6 +926,7 @@ export function setupIssuesCommands(program) {
         .option("--project <project>", "filter by project name or ID")
         .option("--no-project", "filter issues with no project assigned")
         .option("--status <status>", "filter by status (comma-separated)")
+        .option("--include-closed", "include issues in terminal states (Done / Canceled). Default is to exclude them; pass this flag to see everything. Ignored when --status is set (explicit choice wins).")
         .option("--labels <labels>", "filter by labels (comma-separated names)")
         .option("--label <labels>", "alias for --labels")
         .option("--priority <priority>", "filter by priority (comma-separated: urgent,high,medium,low,none or 0-4)")
@@ -965,7 +997,10 @@ export function setupIssuesCommands(program) {
         .option("--field <name>", 'Extract a single named section from the issue description (e.g. "Done when"). ' +
         "Matches H2/H3 headers and bold pseudo-headers case-insensitively. " +
         "Outputs the section text only — no JSON envelope. Single-issue only.")
-        .addHelpText("after", '\nBoth UUID and identifiers like ABC-123 are supported.\nMultiple IDs: el-linear issue get DEV-123 DEV-456 DEV-789\nExtract a section: el-linear issue read DEV-123 --field "Done when"')
+        .option("--sections <names>", 'Extract multiple named description sections in one call (comma-separated, e.g. "Done when,Out of scope"). ' +
+        "Single-issue only. Returns a JSON envelope { identifier, sections: { name -> text|null } }; missing sections appear as null + a _warnings entry. " +
+        "Sibling of --field (singular). Named --sections rather than --fields because the program already has a global --fields for output-key filtering.")
+        .addHelpText("after", '\nBoth UUID and identifiers like ABC-123 are supported.\nMultiple IDs: el-linear issue get DEV-123 DEV-456 DEV-789\nExtract a section: el-linear issue read DEV-123 --field "Done when"\nMulti-section: el-linear issue read DEV-123 --sections "Done when,Out of scope"')
         .action(handleAsyncCommand(readIssues));
     issues
         .command("update <issueId>")

package/dist/commands/read-shortcut.js

@@ -1,8 +1,8 @@
 import { downloadLinearUploads } from "../utils/download-uploads.js";
-import { extractField } from "../utils/extract-field.js";
+import { extractField, extractFields } from "../utils/extract-field.js";
 import { createFileService } from "../utils/file-service.js";
 import { createIssuesService } from "../utils/issues-service-bootstrap.js";
-import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
 /**
  * Issue ID pattern: 1-5 uppercase letters, dash, 1+ digits (e.g. ADM-652, DEV-12).
@@ -23,7 +23,10 @@ export function setupReadShortcut(program) {
         .option("--field <name>", 'Extract a single named section from the issue description (e.g. "Done when"). ' +
         "Matches H2/H3 headers and bold pseudo-headers case-insensitively. " +
         "Outputs the section text only — no JSON envelope.")
-        .addHelpText("after", '\nExamples:\n  el-linear read ADM-652\n  el-linear get DEV-123 DEV-456\n  el-linear ADM-652          (auto-detected)\n  el-linear read DEV-123 --field "Done when"   (just that section)')
+        .option("--sections <names>", 'Extract multiple named description sections in one call (comma-separated, e.g. "Done when,Out of scope,Steps"). ' +
+        "Single-issue only. Returns a JSON envelope { identifier, sections: { name -> text|null } }; missing sections appear as null + a _warnings entry. " +
+        "Sibling of --field (singular). Named --sections rather than --fields because the program already has a global --fields for output-key filtering.")
+        .addHelpText("after", '\nExamples:\n  el-linear read ADM-652\n  el-linear get DEV-123 DEV-456\n  el-linear ADM-652          (auto-detected)\n  el-linear read DEV-123 --field "Done when"   (just that section)\n  el-linear read DEV-123 --sections "Done when,Out of scope"')
         .action(handleAsyncCommand(readIssues));
     // Catch-all: if argv looks like `el-linear ADM-652 [DEV-123 ...]`, run read
     const originalParse = program.parse.bind(program);
@@ -61,12 +64,28 @@ export async function readIssues(issueIds, options, command) {
     const { issuesService } = await createIssuesService(rootOpts);
     const fileService = await createFileService(rootOpts);
     const fieldName = typeof options.field === "string" ? options.field : null;
-    // --field is single-issue only. With multiple issues, a section
-    // extraction can't sensibly fan out to N different bodies — the
-    // caller almost always wants one section from one issue.
-    if (fieldName && issueIds.length > 1) {
-        throw new Error("--field is single-issue only; pass exactly one issueId. " +
-            "For multiple issues, drop --field and use --jq or --format summary.");
+    const sectionsRaw = typeof options.sections === "string" ? options.sections : null;
+    if (fieldName && sectionsRaw) {
+        throw new Error("--field and --sections are mutually exclusive. Use --field for a single section (plain-text output) or --sections for multiple (JSON map).");
+    }
+    // Both --field and --sections are single-issue only — section extraction
+    // can't sensibly fan out to N different bodies, the caller almost always
+    // wants the named sections of one issue.
+    if ((fieldName || sectionsRaw) && issueIds.length > 1) {
+        throw new Error("--field / --sections are single-issue only; pass exactly one issueId. " +
+            "For multiple issues, drop the section flags and use --jq or --format summary.");
+    }
+    // Parse the comma-separated --sections list once. Preserve the caller's
+    // order, trim each entry, and drop empties so trailing commas don't
+    // surface as ghost "" sections.
+    const sectionNames = sectionsRaw
+        ? sectionsRaw
+            .split(",")
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0)
+        : null;
+    if (sectionNames !== null && sectionNames.length === 0) {
+        throw new Error("--sections was empty after trimming. Pass a comma-separated list of section names.");
     }
     if (issueIds.length === 1) {
         const issue = await issuesService.getIssueById(issueIds[0]);
@@ -83,13 +102,38 @@ export async function readIssues(issueIds, options, command) {
             process.stdout.write(`${section}\n`);
             return;
         }
+        if (sectionNames !== null) {
+            const sectionsMap = extractFields(resolved.description ?? "", sectionNames);
+            const sections = {};
+            const missing = [];
+            for (const [name, text] of sectionsMap) {
+                sections[name] = text;
+                if (text === null)
+                    missing.push(name);
+            }
+            if (missing.length > 0) {
+                // Coalesce: one warning naming every missing section is denser than
+                // N entries and easier for an agent to act on (cycle-1 nit).
+                outputWarning(`sections not found in ${resolved.identifier}'s description: ${missing
+                    .map((n) => `"${n}"`)
+                    .join(", ")}`);
+            }
+            outputSuccess({
+                identifier: resolved.identifier,
+                sections,
+            });
+            return;
+        }
         outputSuccess(resolved);
     }
     else {
-        const results = await Promise.all(issueIds.map(async (id) => {
-            const issue = await issuesService.getIssueById(id);
-            return downloadLinearUploads(issue, fileService);
-        }));
+        // DEV-4477: one batched GraphQL call instead of N parallel single-issue
+        // queries. The service preserves input order and throws notFoundError
+        // on any missing ref. Attachment download still fans out per-issue —
+        // that's HTTP, not GraphQL, and downloadLinearUploads is a no-op when
+        // there's nothing to download.
+        const issues = await issuesService.getIssuesByRefs(issueIds);
+        const results = await Promise.all(issues.map((issue) => downloadLinearUploads(issue, fileService)));
         outputSuccess(results);
     }
 }

package/dist/queries/common.d.ts

@@ -1,2 +1,2 @@
-export declare const COMPLETE_ISSUE_FRAGMENT = "\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";
-export declare const COMPLETE_ISSUE_WITH_COMMENTS_FRAGMENT = "\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";
+export declare const COMPLETE_ISSUE_FRAGMENT = "\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";
+export declare const COMPLETE_ISSUE_WITH_COMMENTS_FRAGMENT = "\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";

package/dist/queries/common.js

@@ -16,6 +16,7 @@ const ISSUE_STATE_FRAGMENT = `
   state {
     id
     name
+    type
   }
 `;
 const ISSUE_ASSIGNEE_FRAGMENT = `

package/dist/queries/issue-tree.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 declare const MIN_TREE_DEPTH = 1;
+export declare const MAX_TREE_DEPTH = 5;
+export declare const DEFAULT_TREE_DEPTH = 3;
+export declare function buildIssueTreeQuery(depth: number): string;
+/**
+ * Shape of a single tree node — used for both the GraphQL response and
+ * the post-filter return value (after `--include-closed` is applied
+ * client-side).
+ */
+export interface IssueTreeNode {
+    id: string;
+    identifier: string;
+    title: string;
+    state: {
+        id: string;
+        name: string;
+        type: string;
+    } | null;
+    assignee: {
+        id: string;
+        name: string;
+    } | null;
+    children?: {
+        nodes: IssueTreeNode[];
+    };
+}
+export interface GetIssueTreeResponse {
+    issue: IssueTreeNode | null;
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "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",
@@ -52,7 +52,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.2",
-    "@linear/sdk": "^84.0.0",
+    "@linear/sdk": "^86.0.0",
     "commander": "^14.0.0",
     "picocolors": "^1.1.1"
   },