@enrichlayer/el-linear 1.9.0 → 1.15.0

package/dist/commands/issues.js

@@ -1,25 +1,26 @@
 import { execFileSync } from "node:child_process";
 import { loadConfig } from "../config/config.js";
+import { enrichProjectResolverError, enrichValidationErrors, } from "../config/error-enrichment.js";
 import { enforceValidation, validateIssueCreation, } from "../config/issue-validation.js";
 import { resolveAssignee, resolveLabels, resolveMember, resolveTeam, } from "../config/resolver.js";
 import { resolveDefaultStatus } from "../config/status-defaults.js";
 import { enforceTerms } from "../config/term-enforcer.js";
-import { LIST_COMMENTS_QUERY } from "../queries/comments.js";
-import { GET_ISSUE_RELATIONS_QUERY, GET_ISSUE_STATE_HISTORY_QUERY, ISSUE_RELATION_CREATE_MUTATION, SCAN_ISSUES_QUERY, } from "../queries/issues.js";
-import { autoLinkReferences, } from "../utils/auto-link-references.js";
+import { GET_ISSUE_RELATIONS_QUERY, GET_ISSUE_STATE_HISTORY_QUERY, } from "../queries/issues.js";
 import { createFileService } from "../utils/file-service.js";
 import { applyFooter } from "../utils/footer.js";
 import { createGraphQLAttachmentsService } from "../utils/graphql-attachments-service.js";
-import { GraphQLIssuesService, } from "../utils/graphql-issues-service.js";
 import { createGraphQLService, } from "../utils/graphql-service.js";
+import { createIssuesService } from "../utils/issues-service-bootstrap.js";
 import { createLinearService, } from "../utils/linear-service.js";
 import { logger } from "../utils/logger.js";
-import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
+import { handleAsyncCommand, outputSuccess, outputWarning, warnIfTruncated, } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { formatCsv, formatMarkdown, formatTable, } from "../utils/table-formatter.js";
-import { parsePriorityFilter, splitList, validatePriority, } from "../utils/validators.js";
+import { parsePositiveInt, parsePriorityFilter, splitList, validatePriority, } from "../utils/validators.js";
 import { gitCheckoutBranch, toBranchName } from "./issues/branch.js";
-import { maybeAutoLink, prepareAutoLinkedDescription, prepareDescriptionRewrite, pushDescriptionUpdate, readDescriptionFile, resolveDescription, } from "./issues/description.js";
+import { maybeAutoLink, prepareAutoLinkedDescription, readDescriptionFile, resolveDescription, } from "./issues/description.js";
+import { handleLinkReferencesIssue } from "./issues/link-references.js";
+import { buildIncomingRelationEntries, buildOutgoingRelationEntries, createRelations, } from "./issues/relations.js";
 import { readIssues } from "./read-shortcut.js";
 const IMAGE_EXTENSIONS = new Set([
     ".png",
@@ -35,54 +36,10 @@ function isImageFile(filename) {
     const ext = filename.lastIndexOf(".");
     return ext !== -1 && IMAGE_EXTENSIONS.has(filename.slice(ext).toLowerCase());
 }
-function transformIssueRelation(rel) {
-    const issue = rel.issue;
-    const relatedIssue = rel.relatedIssue;
-    return {
-        id: rel.id,
-        type: rel.type,
-        issue: {
-            id: issue.id,
-            identifier: issue.identifier,
-            title: issue.title,
-        },
-        relatedIssue: {
-            id: relatedIssue.id,
-            identifier: relatedIssue.identifier,
-            title: relatedIssue.title,
-        },
-    };
-}
-async function createRelations(sourceId, options, graphQLService, linearService) {
-    const relations = [];
-    const relationSpecs = [
-        { option: "relatedTo", type: "related" },
-        { option: "blocks", type: "blocks" },
-        { option: "blockedBy", type: "blocks", reverse: true },
-        { option: "duplicateOf", type: "duplicate" },
-    ];
-    for (const spec of relationSpecs) {
-        const value = options[spec.option];
-        if (!value) {
-            continue;
-        }
-        for (const id of splitList(value)) {
-            const targetId = await linearService.resolveIssueId(id);
-            const rel = await graphQLService.rawRequest(ISSUE_RELATION_CREATE_MUTATION, {
-                input: {
-                    issueId: spec.reverse ? targetId : sourceId,
-                    relatedIssueId: spec.reverse ? sourceId : targetId,
-                    type: spec.type,
-                },
-            });
-            const create = rel.issueRelationCreate;
-            const issueRelation = create?.issueRelation;
-            relations.push(transformIssueRelation(issueRelation));
-        }
-    }
-    return relations;
-}
 function validateUpdateOptions(options) {
+    if (options.delegate && options.clearDelegate) {
+        throw new Error("Cannot use --delegate and --clear-delegate together");
+    }
     if (options.parentTicket && options.clearParentTicket) {
         throw new Error("Cannot use --parent-ticket and --clear-parent-ticket together");
     }
@@ -108,7 +65,7 @@ function validateUpdateOptions(options) {
         throw new Error("Cannot use --description and --append-description together");
     }
 }
-function buildUpdateArgs(issueId, options, assigneeId) {
+function buildUpdateArgs(issueId, options, assigneeId, delegateId) {
     let labelIds;
     if (options.clearLabels) {
         labelIds = [];
@@ -131,6 +88,7 @@ function buildUpdateArgs(issueId, options, assigneeId) {
         statusId: options.status,
         priority: priorityInput ? validatePriority(priorityInput) : undefined,
         assigneeId,
+        delegateId,
         projectId: options.project,
         labelIds,
         parentId: options.parentTicket || (options.clearParentTicket ? null : undefined),
@@ -183,44 +141,61 @@ function sortIssues(issues, sort) {
     }
     return sorted;
 }
+/**
+ * Map commander's `options.project` (string | false | undefined) onto the
+ * `SearchIssueArgs.project` discriminant. Commander turns `--no-project`
+ * into `false`; a missing flag is `undefined`; a string is the project
+ * name or UUID to filter to.
+ */
+function resolveProjectFlag(value) {
+    if (value === false)
+        return { kind: "none" };
+    if (value)
+        return { kind: "id", id: value };
+    return undefined;
+}
 async function handleListIssues(options, command) {
     if (options.label && !options.labels) {
         options.labels = options.label;
     }
     const rootOpts = getRootOpts(command);
-    const graphQLService = await createGraphQLService(rootOpts);
-    const linearService = await createLinearService(rootOpts);
-    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    const { issuesService } = await createIssuesService(rootOpts);
     const hasFilters = options.team ||
         options.labels ||
         options.status ||
         options.assignee ||
+        options.delegate ||
         options.project ||
         options.project === false ||
         options.priority;
+    const limit = parsePositiveInt(options.limit, "--limit");
     if (hasFilters) {
         const searchArgs = {
             teamId: options.team ? resolveTeam(options.team) : undefined,
             assigneeId: options.assignee
                 ? await resolveAssignee(options.assignee, rootOpts)
                 : undefined,
-            projectId: options.project || undefined,
-            noProject: options.project === false,
+            delegateId: options.delegate
+                ? resolveMember(options.delegate)
+                : undefined,
+            project: resolveProjectFlag(options.project),
             labelNames: options.labels ? splitList(options.labels) : undefined,
             status: options.status ? splitList(options.status) : undefined,
             priority: options.priority
                 ? parsePriorityFilter(options.priority)
                 : undefined,
             orderBy: options.sort === "created" ? "createdAt" : "updatedAt",
-            limit: Number.parseInt(options.limit, 10),
+            limit,
         };
         const result = sortIssues(await issuesService.searchIssues(searchArgs), options.sort);
+        warnIfTruncated(result.length, limit);
         outputIssues(result, options.format, options.fields, {
             team: options.team,
         });
     }
     else {
-        const result = sortIssues(await issuesService.getIssues(Number.parseInt(options.limit, 10)), options.sort);
+        const result = sortIssues(await issuesService.getIssues(limit), options.sort);
+        warnIfTruncated(result.length, limit);
         outputIssues(result, options.format, options.fields, {});
     }
 }
@@ -229,27 +204,58 @@ async function handleSearchIssues(query, options, command) {
         options.labels = options.label;
     }
     const rootOpts = getRootOpts(command);
-    const graphQLService = await createGraphQLService(rootOpts);
-    const linearService = await createLinearService(rootOpts);
-    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    const { issuesService } = await createIssuesService(rootOpts);
+    const limit = parsePositiveInt(options.limit, "--limit");
     const searchArgs = {
         query,
         teamId: options.team ? resolveTeam(options.team) : undefined,
         assigneeId: options.assignee
             ? await resolveAssignee(options.assignee, rootOpts)
             : undefined,
-        projectId: options.project || undefined,
-        noProject: options.project === false,
+        delegateId: options.delegate
+            ? resolveMember(options.delegate)
+            : undefined,
+        project: resolveProjectFlag(options.project),
         status: options.status ? splitList(options.status) : undefined,
         labelNames: options.labels ? splitList(options.labels) : undefined,
         priority: options.priority
             ? parsePriorityFilter(options.priority)
             : undefined,
-        limit: Number.parseInt(options.limit, 10),
+        limit,
     };
     const result = sortIssues(await issuesService.searchIssues(searchArgs), options.sort);
+    warnIfTruncated(result.length, limit);
     outputIssues(result, options.format, options.fields, { query });
 }
+/**
+ * Run an `issuesService.createIssue` / `.updateIssue` call and, if it
+ * throws a `Project "<input>" not found` resolver error, enrich the
+ * message with team-scoped project suggestions before re-throwing. Same
+ * suggestion shape as the `Missing --project` validation path — agents
+ * get a concrete retry list whether the failure was "forgot to pass
+ * --project" or "passed --project but it didn't resolve".
+ *
+ * Best-effort: any other error class flows through unchanged, and any
+ * failure inside enrichment falls back to the original message.
+ */
+async function withProjectResolverEnrichment(fn, options, services) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof Error && options.team) {
+            const enriched = await enrichProjectResolverError(err.message, { team: options.team, title: options.title }, services);
+            if (enriched !== err.message) {
+                // Mutate in place rather than throwing a fresh Error — preserves
+                // the original error subclass and stack trace so consumers that
+                // rely on `instanceof` (or read `.stack` via EL_LINEAR_DEBUG=1)
+                // keep working. Only the user-facing message changes.
+                err.message = enriched;
+            }
+        }
+        throw err;
+    }
+}
 async function resolveCreateInputs(title, options, rootOpts) {
     const config = loadConfig();
     enforceTerms([title, options.description], { strict: options.strict });
@@ -291,6 +297,22 @@ async function resolveCreateInputs(title, options, rootOpts) {
         if (validationResult.normalizedLabels) {
             options.labels = validationResult.normalizedLabels.join(",");
         }
+        // Match the team-resolution rule used for the create call below
+        // (line ~389): fall back to config.defaultTeam when --team is omitted.
+        // Without this, users with a configured default team would see bare
+        // validation errors with no suggestions — the exact opposite of what
+        // the AI-coding-agent use case needs.
+        const enrichTeam = options.team || config.defaultTeam;
+        if (validationResult.errors.length > 0 && enrichTeam) {
+            try {
+                const graphQLService = await createGraphQLService(rootOpts);
+                const linearService = await createLinearService(rootOpts);
+                await enrichValidationErrors(validationResult, { team: enrichTeam, title }, { graphQLService, linearService });
+            }
+            catch {
+                // Best-effort enrichment — never block the original error.
+            }
+        }
         enforceValidation(validationResult);
     }
     if (!effectivePriorityInput) {
@@ -301,9 +323,16 @@ async function resolveCreateInputs(title, options, rootOpts) {
     const assigneeId = effectiveAssignee
         ? await resolveAssignee(effectiveAssignee, rootOpts)
         : undefined;
+    const delegateId = options.delegate
+        ? resolveMember(options.delegate)
+        : undefined;
     let labelIds = [];
     if (options.labels) {
-        labelIds = resolveLabels(splitList(options.labels), teamInput);
+        // No `teamInput`: team-scoped labels are resolved API-side against the
+        // issue's *final* team, which `createIssue` may auto-switch to match
+        // the project. Resolving a team-scoped config UUID here would pin the
+        // label to the pre-switch team and Linear would reject the mismatch.
+        labelIds = resolveLabels(splitList(options.labels));
     }
     if (options.claude) {
         const claudeId = config.labels.workspace.claude;
@@ -327,6 +356,7 @@ async function resolveCreateInputs(title, options, rootOpts) {
         teamInput,
         teamId,
         assigneeId,
+        delegateId,
         labelIds,
         status,
         subscriberIds,
@@ -365,7 +395,7 @@ function buildDescriptionWithAttachments(baseDescription, uploadResults) {
 }
 async function handleCreateIssue(title, options, command) {
     const rootOpts = getRootOpts(command);
-    const { teamInput, teamId, assigneeId, labelIds, status, subscriberIds, priority, } = await resolveCreateInputs(title ?? "", options, rootOpts);
+    const { teamInput, teamId, assigneeId, delegateId, labelIds, status, subscriberIds, priority, } = await resolveCreateInputs(title ?? "", options, rootOpts);
     const uploadResults = await uploadAttachmentsIfNeeded(options, rootOpts);
     const descriptionWithAttachments = buildDescriptionWithAttachments(resolveDescription(options) || "", uploadResults);
     // Append messageFooter (config or --footer flag) so auto-link picks up any
@@ -377,14 +407,12 @@ async function handleCreateIssue(title, options, command) {
         footer: explicitFooter,
         noFooter,
     }) ?? "";
-    const graphQLService = await createGraphQLService(rootOpts);
-    const linearService = await createLinearService(rootOpts);
-    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    const { graphQLService, linearService, issuesService } = await createIssuesService(rootOpts);
     // Wrap valid issue identifiers as markdown links before creating, so the description
     // saved on Linear has clickable refs from the start. Self-reference can't apply here
     // because the issue doesn't exist yet — pass undefined.
     const prepared = await prepareAutoLinkedDescription(description || undefined, options, undefined, linearService, graphQLService);
-    const result = await issuesService.createIssue({
+    const result = await withProjectResolverEnrichment(() => issuesService.createIssue({
         // title is omitted when --from-template is set without an override,
         // so Linear copies the template's title server-side.
         ...(title ? { title } : {}),
@@ -392,6 +420,7 @@ async function handleCreateIssue(title, options, command) {
         teamInput,
         description: prepared.description,
         assigneeId,
+        delegateId,
         priority,
         projectId: options.project,
         statusId: status,
@@ -407,7 +436,7 @@ async function handleCreateIssue(title, options, command) {
         ...(typeof options.fromTemplate === "string" && options.fromTemplate
             ? { templateId: options.fromTemplate }
             : {}),
-    });
+    }), { team: options.team ?? loadConfig().defaultTeam, title }, { graphQLService, linearService });
     const relations = await createRelations(result.id, options, graphQLService, linearService);
     // Pass the ORIGINAL description (pre-wrap) so the extractor's prose-keyword inference
     // ("blocked by", "duplicates", etc.) sees `keyword DEV-100` instead of `keyword [DEV-100](url)`.
@@ -460,22 +489,19 @@ async function handleHistoryIssue(issueId, _options, command) {
     const graphQLService = await createGraphQLService(rootOpts);
     const linearService = await createLinearService(rootOpts);
     const resolvedId = await linearService.resolveIssueId(issueId);
-    const result = await graphQLService.rawRequest(GET_ISSUE_STATE_HISTORY_QUERY, {
-        id: resolvedId,
-    });
+    const result = await graphQLService.rawRequest(GET_ISSUE_STATE_HISTORY_QUERY, { id: resolvedId });
     if (!result.issue) {
         throw new Error(`Issue "${issueId}" not found`);
     }
     const issue = result.issue;
-    const stateHistory = issue.stateHistory;
-    const spans = (stateHistory?.nodes ?? []).map((span) => ({
+    const spans = issue.stateHistory.nodes.map((span) => ({
         state: {
             id: span.state.id,
             name: span.state.name,
             type: span.state.type,
         },
         startedAt: span.startedAt,
-        endedAt: span.endedAt || undefined,
+        endedAt: span.endedAt ?? undefined,
     }));
     outputSuccess({
         id: issue.id,
@@ -499,82 +525,19 @@ async function handleRelateIssue(issueId, options, command) {
         meta: { count: relations.length, source: issueId },
     });
 }
-/**
- * Invert relation type for incoming (inverse) relations so the output
- * reads naturally from the perspective of the queried issue.
- * e.g. if DEV-100 "blocks" DEV-200, and we query DEV-200,
- * the inverse relation type is "blocks" but direction is incoming → "blockedBy".
- */
-function normalizeInverseType(type) {
-    if (type === "blocks") {
-        return "blockedBy";
-    }
-    return type;
-}
-function buildRelatedIssueSummary(peer) {
-    const state = peer.state;
-    const assignee = peer.assignee;
-    const team = peer.team;
-    return {
-        id: peer.id,
-        identifier: peer.identifier,
-        title: peer.title,
-        ...(state
-            ? { state: { id: state.id, name: state.name } }
-            : {}),
-        ...(peer.priority == null ? {} : { priority: peer.priority }),
-        ...(assignee
-            ? {
-                assignee: {
-                    id: assignee.id,
-                    name: assignee.name,
-                },
-            }
-            : {}),
-        ...(team
-            ? {
-                team: {
-                    id: team.id,
-                    key: team.key,
-                    name: team.name,
-                },
-            }
-            : {}),
-    };
-}
-function buildRelationEntries(nodes, peerKey, direction, normalizeType) {
-    const entries = [];
-    for (const rel of nodes ?? []) {
-        const peer = rel[peerKey];
-        if (!peer) {
-            continue;
-        }
-        entries.push({
-            id: rel.id,
-            type: normalizeType(rel.type),
-            direction,
-            issue: buildRelatedIssueSummary(peer),
-        });
-    }
-    return entries;
-}
 async function handleRelatedIssues(issueId, _options, command) {
     const rootOpts = getRootOpts(command);
     const graphQLService = await createGraphQLService(rootOpts);
     const linearService = await createLinearService(rootOpts);
     const resolvedId = await linearService.resolveIssueId(issueId);
-    const result = await graphQLService.rawRequest(GET_ISSUE_RELATIONS_QUERY, {
-        id: resolvedId,
-    });
+    const result = await graphQLService.rawRequest(GET_ISSUE_RELATIONS_QUERY, { id: resolvedId });
     if (!result.issue) {
         throw new Error(`Issue "${issueId}" not found`);
     }
     const issue = result.issue;
-    const relations = issue.relations;
-    const inverseRelations = issue.inverseRelations;
     const entries = [
-        ...buildRelationEntries(relations?.nodes, "relatedIssue", "outgoing", (raw) => raw),
-        ...buildRelationEntries(inverseRelations?.nodes, "issue", "incoming", normalizeInverseType),
+        ...buildOutgoingRelationEntries(issue.relations.nodes),
+        ...buildIncomingRelationEntries(issue.inverseRelations.nodes),
     ];
     outputSuccess({
         id: issue.id,
@@ -584,157 +547,52 @@ async function handleRelatedIssues(issueId, _options, command) {
         meta: { count: entries.length },
     });
 }
-async function fetchCommentBodies(issueUuid, graphQLService) {
-    const result = await graphQLService.rawRequest(LIST_COMMENTS_QUERY, {
-        issueId: issueUuid,
-        first: 250,
-    });
-    const issue = result.issue;
-    const comments = issue?.comments;
-    const nodes = comments?.nodes ?? [];
-    return nodes
-        .map((c) => c.body)
-        .filter((b) => typeof b === "string" && b.length > 0);
-}
-async function linkReferencesForIssue(args) {
-    const comments = args.includeComments
-        ? await fetchCommentBodies(args.issueUuid, args.graphQLService)
-        : undefined;
-    return autoLinkReferences({
-        issueId: args.issueUuid,
-        identifier: args.identifier,
-        description: args.description,
-        comments,
-        dryRun: args.dryRun,
-        graphQLService: args.graphQLService,
-        linearService: args.linearService,
-        preResolved: args.preResolved,
-    });
-}
-async function handleLinkReferencesSingle(issueId, options, graphQLService, linearService) {
-    const resolvedId = await linearService.resolveIssueId(issueId);
-    // GET_ISSUE_RELATIONS_QUERY also returns description, so this single call gives us everything
-    // we need for the description-only path. Comments are fetched separately on demand.
-    const issueResult = await graphQLService.rawRequest(GET_ISSUE_RELATIONS_QUERY, {
-        id: resolvedId,
-    });
-    if (!issueResult.issue) {
-        throw new Error(`Issue "${issueId}" not found`);
-    }
-    const issue = issueResult.issue;
-    const identifier = issue.identifier;
-    const description = issue.description ?? "";
-    const dryRun = Boolean(options.dryRun);
-    const includeComments = Boolean(options.includeComments);
-    const rewriteDescription = Boolean(options.rewriteDescription);
-    // If rewriting, validate refs once up front so we can both wrap the description and
-    // pass the resolved map down to autoLink — avoids a second resolve round trip.
-    const rewrite = rewriteDescription
-        ? await prepareDescriptionRewrite(description, identifier, linearService, graphQLService)
-        : { preResolved: undefined, wrapped: undefined };
-    const autoLinked = await linkReferencesForIssue({
-        issueUuid: resolvedId,
-        identifier,
-        description,
-        includeComments,
-        dryRun,
-        graphQLService,
-        linearService,
-        preResolved: rewrite.preResolved,
-    });
-    let descriptionRewritten = false;
-    if (rewriteDescription && rewrite.wrapped && !dryRun) {
-        await pushDescriptionUpdate(resolvedId, rewrite.wrapped, graphQLService);
-        descriptionRewritten = true;
-    }
+async function handleStartIssue(issueId, _options, command) {
+    const rootOpts = getRootOpts(command);
+    const { issuesService } = await createIssuesService(rootOpts);
+    const result = await issuesService.startIssue(issueId);
     outputSuccess({
-        id: resolvedId,
-        identifier,
-        title: issue.title,
-        autoLinked,
-        ...(rewriteDescription
-            ? {
-                descriptionRewritten,
-                ...(dryRun && rewrite.wrapped
-                    ? { descriptionPreview: rewrite.wrapped }
-                    : {}),
-            }
-            : {}),
-        meta: {
-            dryRun,
-            includeComments,
-            ...(rewriteDescription ? { rewriteDescription: true } : {}),
-        },
+        ...result.issue,
+        started: result.started,
+        ...(result.previousState ? { previousState: result.previousState } : {}),
+        ...(result.targetState ? { targetState: result.targetState } : {}),
     });
 }
-async function handleLinkReferencesBatch(teamInput, options, graphQLService, linearService) {
-    const teamId = resolveTeam(teamInput);
-    const limit = options.limit
-        ? Number.parseInt(options.limit, 10)
-        : 100;
-    if (!Number.isFinite(limit) || limit <= 0) {
-        throw new Error(`--limit must be a positive integer, got: ${options.limit}`);
-    }
-    const dryRun = Boolean(options.dryRun);
-    const includeComments = Boolean(options.includeComments);
-    const scan = await graphQLService.rawRequest(SCAN_ISSUES_QUERY, {
-        filter: { team: { id: { eq: teamId } } },
-        first: limit,
-    });
-    const issues = scan.issues?.nodes;
-    const nodes = issues ?? [];
-    const entries = [];
-    for (const node of nodes) {
-        const issueUuid = node.id;
-        const identifier = node.identifier;
-        const description = node.description ?? "";
-        const autoLinked = await linkReferencesForIssue({
-            issueUuid,
-            identifier,
-            description,
-            includeComments,
-            dryRun,
-            graphQLService,
-            linearService,
-        });
-        entries.push({ identifier, autoLinked });
-    }
-    // Summary counts across the batch
-    const totalLinked = entries.reduce((n, e) => n + e.autoLinked.linked.length, 0);
-    const totalSkipped = entries.reduce((n, e) => n + e.autoLinked.skipped.length, 0);
-    const totalFailed = entries.reduce((n, e) => n + e.autoLinked.failed.length, 0);
-    outputSuccess({
-        data: entries,
-        meta: {
-            count: entries.length,
-            team: teamInput,
-            dryRun,
-            includeComments,
-            totals: {
-                linked: totalLinked,
-                skipped: totalSkipped,
-                failed: totalFailed,
-            },
-        },
-    });
+// Field-mutating options on `issues update`, post alias-normalization.
+// If none of these are set, an `issues update` invocation that carries only
+// relation flags is treated as relation-only (see handleUpdateIssue): it must
+// behave exactly like `issues relate` and NOT issue an issueUpdate mutation,
+// which would otherwise apply the config defaultPriority fallback and bump the
+// issue's activity for what the user intended as a pure relation add.
+const UPDATE_FIELD_OPTION_KEYS = [
+    "title",
+    "description",
+    "appendDescription",
+    "status",
+    "priority",
+    "assignee",
+    "delegate",
+    "clearDelegate",
+    "project",
+    "labels",
+    "clearLabels",
+    "parentTicket",
+    "clearParentTicket",
+    "projectMilestone",
+    "clearProjectMilestone",
+    "cycle",
+    "clearCycle",
+    "dueDate",
+    "clearDueDate",
+];
+function hasFieldUpdates(options) {
+    return UPDATE_FIELD_OPTION_KEYS.some((key) => options[key] !== undefined && options[key] !== false);
 }
-async function handleLinkReferencesIssue(issueIdOrTeamFlag, options, command) {
-    const rootOpts = getRootOpts(command);
-    const graphQLService = await createGraphQLService(rootOpts);
-    const linearService = await createLinearService(rootOpts);
-    if (options.team) {
-        if (issueIdOrTeamFlag) {
-            throw new Error("Provide either an issueId positional argument OR --team, not both. With --team, omit the issueId.");
-        }
-        if (options.rewriteDescription) {
-            throw new Error("--rewrite-description is single-issue only. Use it case by case (one issueId per invocation) — bulk description rewrites bot-author the whole team's history.");
-        }
-        return handleLinkReferencesBatch(options.team, options, graphQLService, linearService);
-    }
-    if (!issueIdOrTeamFlag) {
-        throw new Error("issueId is required (or use --team <key> to scan a whole team)");
-    }
-    return handleLinkReferencesSingle(issueIdOrTeamFlag, options, graphQLService, linearService);
+function hasRelationFlags(options) {
+    return Boolean(options.relatedTo ||
+        options.blocks ||
+        options.blockedBy ||
+        options.duplicateOf);
 }
 async function handleUpdateIssue(issueId, options, command) {
     // Normalize aliases
@@ -744,19 +602,37 @@ async function handleUpdateIssue(issueId, options, command) {
     if (options.label && !options.labels) {
         options.labels = options.label;
     }
+    if (options.parent && !options.parentTicket) {
+        options.parentTicket = options.parent;
+    }
     // Resolve --description-file before validation
     if (options.descriptionFile) {
         options.description = readDescriptionFile(options.descriptionFile);
     }
     validateUpdateOptions(options);
     const rootOpts = getRootOpts(command);
-    const graphQLService = await createGraphQLService(rootOpts);
-    const linearService = await createLinearService(rootOpts);
+    const { graphQLService, linearService, issuesService } = await createIssuesService(rootOpts);
+    // Relation-only update: no field changes, just relation flags. Behave
+    // identically to `issues relate` — never call updateIssue, so no
+    // defaultPriority side effect and no spurious issue activity.
+    if (!hasFieldUpdates(options) && hasRelationFlags(options)) {
+        const sourceId = await linearService.resolveIssueId(issueId);
+        const relations = await createRelations(sourceId, options, graphQLService, linearService);
+        if (relations.length === 0) {
+            throw new Error("Specify at least one of: --related-to, --blocks, --blocked-by, --duplicate-of");
+        }
+        outputSuccess({
+            data: relations,
+            meta: { count: relations.length, source: issueId },
+        });
+        return;
+    }
     if (options.appendDescription) {
         const resolved = await linearService.resolveIssueId(issueId);
-        const current = await graphQLService.rawRequest("query($id: String!) { issue(id: $id) { description } }", { id: resolved });
-        const issue = current.issue;
-        const existing = issue?.description ?? "";
+        const current = await graphQLService.rawRequest("query($id: String!) { issue(id: $id) { description } }", {
+            id: resolved,
+        });
+        const existing = current.issue?.description ?? "";
         options.description = `${existing}\n${options.appendDescription}`;
     }
     if (options.title || options.description) {
@@ -780,12 +656,24 @@ async function handleUpdateIssue(issueId, options, command) {
     if (prepared.description !== undefined) {
         options.description = prepared.description;
     }
-    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
     const assigneeId = options.assignee
         ? await resolveAssignee(options.assignee, rootOpts)
         : undefined;
-    const updateArgs = buildUpdateArgs(issueId, options, assigneeId);
-    const result = await issuesService.updateIssue(updateArgs, options.labelBy || "adding");
+    const delegateId = options.clearDelegate
+        ? null
+        : options.delegate
+            ? resolveMember(options.delegate)
+            : undefined;
+    const updateArgs = buildUpdateArgs(issueId, options, assigneeId, delegateId);
+    const result = await withProjectResolverEnrichment(() => issuesService.updateIssue(updateArgs, options.labelBy || "adding"), {
+        team: options.team ?? loadConfig().defaultTeam,
+        title: options.title,
+    }, { graphQLService, linearService });
+    // Mirror `issues create` / `issues relate`: the --related-to / --blocks /
+    // --blocked-by / --duplicate-of flags create sidebar relations on the
+    // updated issue. Without this, callers wanting to add a relation to an
+    // existing issue have to make a second `issues relate` call.
+    const relations = await createRelations(result.id, options, graphQLService, linearService);
     const autoLinked = originalDescription
         ? await maybeAutoLink({
             issueId: result.id,
@@ -797,7 +685,35 @@ async function handleUpdateIssue(issueId, options, command) {
             linearService,
         })
         : undefined;
-    outputSuccess(autoLinked ? { ...result, autoLinked } : result);
+    outputSuccess({
+        ...result,
+        ...(relations.length > 0 ? { relations } : {}),
+        ...(autoLinked ? { autoLinked } : {}),
+    });
+}
+async function handleArchiveIssue(issueId, _options, command) {
+    const rootOpts = getRootOpts(command);
+    const { issuesService } = await createIssuesService(rootOpts);
+    const result = await issuesService.archiveIssue(issueId);
+    outputSuccess({
+        success: true,
+        archived: true,
+        ...result,
+    });
+}
+async function handleDeleteIssue(issueId, options, command) {
+    const rootOpts = getRootOpts(command);
+    const { issuesService } = await createIssuesService(rootOpts);
+    const permanentlyDelete = Boolean(options.permanentlyDelete || options.hard);
+    const result = await issuesService.deleteIssue(issueId, {
+        permanentlyDelete,
+    });
+    outputSuccess({
+        success: true,
+        deleted: true,
+        permanentlyDeleted: permanentlyDelete,
+        ...result,
+    });
 }
 async function handleRetrolink(options, command) {
     // 1. Read current branch
@@ -839,9 +755,7 @@ async function handleRetrolink(options, command) {
         ? commits.map((msg) => `- ${msg}`).join("\n")
         : `Retrolinked from branch: ${currentBranch}`;
     const rootOpts = getRootOpts(command);
-    const graphQLService = await createGraphQLService(rootOpts);
-    const linearService = await createLinearService(rootOpts);
-    const issuesService = new GraphQLIssuesService(graphQLService, linearService);
+    const { issuesService } = await createIssuesService(rootOpts);
     let result;
     if (options.issue) {
         // Link to existing issue — fetch it and rename branch
@@ -867,7 +781,13 @@ async function handleRetrolink(options, command) {
     let newBranch;
     if (result.branchName) {
         newBranch = toBranchName(result.branchName);
-        execFileSync("git", ["branch", "-m", oldBranch, newBranch], {
+        // `--` BEFORE the ref operands terminates option parsing so a
+        // name starting with `-` (server bug, malicious slug, forked
+        // Linear-compatible API) is parsed as a ref name rather than a
+        // git flag. Defense in depth — the default feature/ prefix
+        // already blocks the common case, but the prefix is configurable
+        // (DEV-4064).
+        execFileSync("git", ["branch", "-m", "--", oldBranch, newBranch], {
             stdio: "pipe",
         });
     }
@@ -889,6 +809,7 @@ export function setupIssuesCommands(program) {
         .option("-l, --limit <number>", "limit results", "25")
         .option("--team <team>", "filter by team key (EL: resolves names)")
         .option("--assignee <assignee>", "filter by assignee (name, alias, or ID)")
+        .option("--delegate <delegate>", "filter by delegated agent (name, alias, or ID)")
         .option("--project <project>", "filter by project name or ID")
         .option("--no-project", "filter issues with no project assigned")
         .option("--labels <labels>", "filter by labels (comma-separated names)")
@@ -897,13 +818,14 @@ export function setupIssuesCommands(program) {
         .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")
-        .option("--fields <fields>", "columns for table/csv (comma-separated: identifier,title,status,priority,assignee,project,team,labels,updated)")
+        .option("--fields <fields>", "columns for table/csv (comma-separated: identifier,title,status,priority,assignee,delegate,project,team,labels,updated)")
         .action(handleAsyncCommand(handleListIssues));
     issues
         .command("search <query>")
         .description("Search issues.")
         .option("--team <team>", "filter by team key, name, or ID")
         .option("--assignee <assignee>", "filter by assignee (name, alias, or ID)")
+        .option("--delegate <delegate>", "filter by delegated agent (name, alias, or ID)")
         .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)")
@@ -924,6 +846,7 @@ export function setupIssuesCommands(program) {
         .option("--template <name>", "use a named description template from config.descriptionTemplates")
         .option("--from-template <id>", "instantiate the issue from a Linear server-side template (UUID from `el-linear templates list`). Sets templateId on the underlying issueCreate mutation; Linear copies the template's title, description, labels, priority, etc. as the new issue's defaults. Override any field with the matching --title / --description / --labels flag.")
         .option("-a, --assignee <assignee>", "assign to user (name, alias, or UUID)")
+        .option("--delegate <delegate>", "delegate implementation to an agent app user (name, alias, or UUID)")
         .option("--no-assignee", "create unassigned even when config.defaultAssignee is set")
         .option("-p, --priority <priority>", "priority: name (none/urgent/high/medium/normal/low) or number (0-4)")
         .option("--project <project>", "add to project (name or ID)")
@@ -935,6 +858,7 @@ export function setupIssuesCommands(program) {
         .option("--cycle <cycle>", "cycle name or ID")
         .option("--status <status>", "status name or ID")
         .option("--parent-ticket <parentId>", "parent issue ID or identifier")
+        .option("--parent <parentId>", "alias for --parent-ticket")
         .option("--subscriber <subscribers>", "subscribers (comma-separated names, aliases, or UUIDs)")
         .option("--strict", "strict brand validation (error instead of warning)")
         .option("--related-to <issues>", "related issues (comma-separated identifiers)")
@@ -952,6 +876,10 @@ export function setupIssuesCommands(program) {
         if (options.label && !options.labels) {
             options.labels = options.label;
         }
+        // Normalize --parent alias to --parent-ticket
+        if (options.parent && !options.parentTicket) {
+            options.parentTicket = options.parent;
+        }
         const title = options.title || titleArg;
         // --from-template lets Linear copy the template's title, so a
         // local title is optional in that path. Without --from-template,
@@ -968,7 +896,10 @@ export function setupIssuesCommands(program) {
         .alias("get")
         .alias("show")
         .description("Get issue details. Accepts multiple IDs for batch retrieval.")
-        .addHelpText("after", "\nBoth UUID and identifiers like ABC-123 are supported.\nMultiple IDs: el-linear issue get DEV-123 DEV-456 DEV-789")
+        .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"')
         .action(handleAsyncCommand(readIssues));
     issues
         .command("update <issueId>")
@@ -984,12 +915,15 @@ export function setupIssuesCommands(program) {
         .option("--state <status>", "alias for --status (new status name or ID)")
         .option("-p, --priority <priority>", "new priority: name (none/urgent/high/medium/normal/low) or number (0-4)")
         .option("--assignee <assignee>", "new assignee (name, alias, or UUID)")
+        .option("--delegate <delegate>", "delegate implementation to an agent app user (name, alias, or UUID)")
+        .option("--clear-delegate", "remove the issue delegate")
         .option("--project <project>", "new project (name or ID)")
         .option("--labels <labels>", "labels (comma-separated names or IDs)")
         .option("--label <labels>", "alias for --labels")
         .option("--label-by <mode>", "how to apply labels: 'adding' (default) or 'overwriting'")
         .option("--clear-labels", "remove all labels from issue")
         .option("--parent-ticket <parentId>", "set parent issue")
+        .option("--parent <parentId>", "alias for --parent-ticket")
         .option("--clear-parent-ticket", "clear parent relationship")
         .option("--project-milestone <milestone>", "set project milestone")
         .option("--clear-project-milestone", "clear project milestone")
@@ -999,12 +933,38 @@ export function setupIssuesCommands(program) {
         .option("--clear-due-date", "clear due date")
         .option("--strict", "strict brand validation")
         .option("--no-auto-link", "skip auto-linking issue references found in the description")
+        .option("--related-to <issues>", "related issues (comma-separated)")
+        .option("--blocks <issues>", "issues this blocks (comma-separated)")
+        .option("--blocked-by <issues>", "issues blocking this (comma-separated)")
+        .option("--duplicate-of <issue>", "mark as duplicate of another issue")
         .action(handleAsyncCommand(handleUpdateIssue));
+    issues
+        .command("archive <issueId>")
+        .description("Archive an issue.")
+        .addHelpText("after", "\nBoth UUID and identifiers like ABC-123 are supported.")
+        .action(handleAsyncCommand(handleArchiveIssue));
+    issues
+        .command("delete <issueId>")
+        .description("Delete (trash) an issue.")
+        .addHelpText("after", "\nBoth UUID and identifiers like ABC-123 are supported. Use --permanently-delete only when you intend to skip Linear's grace period; Linear requires admin permissions.")
+        .option("--permanently-delete", "skip Linear's 30-day grace period (admin only)")
+        .option("--hard", "alias for --permanently-delete")
+        .action(handleAsyncCommand(handleDeleteIssue));
+    issues
+        .command("hard-delete <issueId>")
+        .description("Permanently delete an issue immediately (admin only).")
+        .addHelpText("after", "\nBoth UUID and identifiers like ABC-123 are supported.")
+        .action(handleAsyncCommand((issueId, options, command) => handleDeleteIssue(issueId, { ...options, permanentlyDelete: true }, command)));
     issues
         .command("history <issueId>")
         .description("Show issue state transition history (time in each status).")
         .addHelpText("after", "\nBoth UUID and identifiers like ABC-123 are supported.")
         .action(handleAsyncCommand(handleHistoryIssue));
+    issues
+        .command("start <issueId>")
+        .description("Move an issue to the team's first started workflow state, unless it is already started or terminal.")
+        .addHelpText("after", "\nBoth UUID and identifiers like ABC-123 are supported.")
+        .action(handleAsyncCommand(handleStartIssue));
     issues
         .command("relate <issueId>")
         .description("Create issue relations.")