linear-sdk-cli 0.4.0 → 0.5.1

package/src/config.ts

@@ -3,8 +3,9 @@
  *
  * Two tiers with different trust boundaries:
  *  - Non-secret settings (team, workspace, sort): flag > env > project
- *    config > user config (`~/.config/linear/config.toml`) > the reference
- *    CLI's global config (`~/.config/linear/linear.toml`, read-only).
+ *    config > selected workspace profile (team only) > user config
+ *    (`~/.config/linear/config.toml`) > the reference CLI's global config
+ *    (`~/.config/linear/linear.toml`, read-only).
  *    The project config is the first file found walking cwd → filesystem
  *    root, checking `linear.toml`, `.linear.toml`, `.config/linear.toml` in
  *    each directory — every location schpet/linear-cli 2.5 reads (it checks
@@ -70,7 +71,15 @@ export interface RawSettings {
  * `global` is the reference CLI's `~/.config/linear/linear.toml`, read for
  * non-secret settings only; `keychain` is the OS keyring (API key or human OAuth session).
  */
-export type ConfigSource = "flag" | "env" | "project" | "user" | "global" | "keychain" | "none";
+export type ConfigSource =
+  | "flag"
+  | "env"
+  | "project"
+  | "workspace-profile"
+  | "user"
+  | "global"
+  | "keychain"
+  | "none";
 
 /** Where a stored workspace credential's secret lives. */
 export type CredentialStorage = "file" | "keychain";
@@ -81,6 +90,8 @@ export interface SettingOrigin {
   path?: string;
   /** Exact spelling found in the file (`issue_sort`, not just canonical `sort`). */
   key?: string;
+  /** Workspace slug for a value read from `[workspaces."<slug>"]`. */
+  workspace?: string;
 }
 
 /** The non-secret settings, each with its provenance. */
@@ -102,8 +113,12 @@ export interface ResolvedConfig {
    * needed (see createClient / `auth token`).
    */
   apiKeyError?: CliError;
+  /** Stored choices when selection is ambiguous; never an implicit default. */
+  workspaceChoices?: string[];
   /** Workspace slug whose stored credential was used, if any. */
   credentialWorkspace?: string;
+  /** Selected stored profile whose non-secret metadata may participate. */
+  workspaceProfile?: string;
   team?: string;
   /** Non-secret display workspace setting (separate from credentialWorkspace). */
   workspace?: string;
@@ -174,6 +189,8 @@ interface WorkspaceEntry {
   apiKey?: string;
   /** This workspace uses the isolated `oauth:<slug>` keyring account. */
   oauth?: boolean;
+  /** Non-secret default team for this workspace. */
+  team?: string;
 }
 
 /** Parsed view of the user config: top-level settings + nested workspace creds. */
@@ -328,6 +345,7 @@ function readUserConfig(path: string): UserConfig {
         workspaces[slug] = {
           apiKey: asString(table.api_key),
           oauth: table.oauth === true,
+          team: asString(table.team),
         };
       }
     }
@@ -450,6 +468,8 @@ export function resolveConfig(inputs: ConfigInputs = {}): ResolvedConfig {
   let accessTokenSource: ConfigSource = "none";
   let oauthCredential: OAuthUserCredential | undefined;
   let credentialWorkspace: string | undefined;
+  let workspaceProfile: string | undefined;
+  let workspaceChoices: string[] | undefined;
   let apiKeyError: CliError | undefined;
 
   if (flags.apiKey && flags.accessToken) {
@@ -522,8 +542,9 @@ export function resolveConfig(inputs: ConfigInputs = {}): ResolvedConfig {
         take(slugs[0]!);
       } else if (slugs.length > 1) {
         // Multiple workspaces but no default → ambiguous (deferred).
+        workspaceChoices = slugs;
         apiKeyError = new CliError(
-          `Multiple workspaces are configured (${slugs.join(", ")}) but none is selected. Pass --workspace <slug> or run \`linear auth default <slug>\`.`,
+          `Multiple workspaces are configured (${slugs.join(", ")}) but none is selected. Pass --workspace <slug>, run \`linear config set workspace <slug>\` for this project, or explicitly choose \`linear auth default <slug>\`.`,
           "usage",
         );
       }
@@ -531,8 +552,27 @@ export function resolveConfig(inputs: ConfigInputs = {}): ResolvedConfig {
     }
   }
 
+  // A stored credential binds its own profile. An invocation-scoped credential
+  // never inherits the default/project workspace implicitly; it may bind only
+  // when this invocation explicitly selected a profile by flag or environment
+  // and that profile is actually configured.
+  if (credentialWorkspace && user.workspaces[credentialWorkspace]) {
+    workspaceProfile = credentialWorkspace;
+  } else {
+    const invocationCredential =
+      apiKeySource === "flag" ||
+      apiKeySource === "env" ||
+      accessTokenSource === "flag" ||
+      accessTokenSource === "env";
+    const explicitWorkspace = flags.workspace ?? envSettings.workspace;
+    if (invocationCredential && explicitWorkspace && user.workspaces[explicitWorkspace]) {
+      workspaceProfile = explicitWorkspace;
+    }
+  }
+
   // ----- Non-secret settings (project + global config MAY participate) -----
-  // flag > env > project file > our user file > the reference CLI's global file.
+  // Workspace and sort keep their existing order. Team inserts the selected
+  // workspace profile between project and the legacy top-level user fallback.
   const tiers: Array<[ConfigSource, RawSettings, string | undefined, SettingKeys | undefined]> = [
     ["flag", flags, undefined, undefined],
     ["env", envSettings, undefined, undefined],
@@ -543,13 +583,30 @@ export function resolveConfig(inputs: ConfigInputs = {}): ResolvedConfig {
   const pick = <K extends "team" | "workspace" | "sort">(key: K): string | undefined =>
     tiers.find(([, settings]) => settings[key] !== undefined)?.[1][key];
 
+  const profileTeam = workspaceProfile ? user.workspaces[workspaceProfile]?.team : undefined;
+  const teamTiers: typeof tiers = [
+    ["flag", flags, undefined, undefined],
+    ["env", envSettings, undefined, undefined],
+    ["project", project.settings, projectPath, project.keys],
+    [
+      "workspace-profile",
+      profileTeam ? { team: profileTeam } : {},
+      userPath,
+      profileTeam ? { team: "team" } : undefined,
+    ],
+    ["user", user.settings, userPath, user.settingKeys],
+    ["global", global.settings, globalPath, global.keys],
+  ];
+
   /** Which tier `pick` took the value from, and which file if it was one. */
   const originOf = (key: "team" | "workspace" | "sort"): SettingOrigin => {
-    const hit = tiers.find(([, settings]) => settings[key] !== undefined);
+    const candidates = key === "team" ? teamTiers : tiers;
+    const hit = candidates.find(([, settings]) => settings[key] !== undefined);
     if (!hit) return { source: "none" };
     const origin: SettingOrigin = { source: hit[0], path: hit[2] };
     const spelling = hit[3]?.[key];
     if (spelling !== undefined) origin.key = spelling;
+    if (hit[0] === "workspace-profile") origin.workspace = workspaceProfile;
     return origin;
   };
 
@@ -567,7 +624,9 @@ export function resolveConfig(inputs: ConfigInputs = {}): ResolvedConfig {
     oauthCredential,
     apiKeyError,
     credentialWorkspace,
-    team: pick("team"),
+    workspaceProfile,
+    workspaceChoices,
+    team: teamTiers.find(([, settings]) => settings.team !== undefined)?.[1].team,
     // The display setting walks every tier. Credential selection above uses
     // the flag, env, and project tiers, then the auth-specific user default.
     workspace: pick("workspace"),
@@ -823,6 +882,7 @@ interface WorkspaceTable {
   api_key?: string;
   keyring?: boolean;
   oauth?: boolean;
+  team?: string;
 }
 
 function workspacesTable(obj: Record<string, unknown>): Record<string, WorkspaceTable> {
@@ -946,10 +1006,6 @@ export function writeOAuthCredential(credential: OAuthUserCredential): WriteOAut
       table.keyring = true;
       table.oauth = true;
       ws[slug] = table;
-      if (!asString(obj.default_workspace)) {
-        const reference = readReferenceCredentials(referenceCredentialsPath());
-        if (!reference.defaultWorkspace) obj.default_workspace = slug;
-      }
       writeUserObject(path, obj);
     } catch (err) {
       try {
@@ -1075,10 +1131,6 @@ export function adoptKeyringCredential(
     delete table.api_key;
     table.keyring = true;
     ws[slug] = table;
-    if (!asString(obj.default_workspace)) {
-      const reference = readReferenceCredentials(referenceCredentialsPath());
-      if (!reference.defaultWorkspace) obj.default_workspace = slug;
-    }
     writeUserObject(path, obj);
     return { path, storage: "keychain", keyringLabel: found.keyringLabel };
   });
@@ -1091,8 +1143,8 @@ export function adoptKeyringCredential(
  * no keyring, it is written as `api_key` in the 0600 file — the latter without
  * complaint, since a platform is not an error. Either way the OTHER form for
  * the same slug is dropped from the file, so a re-login moves the key rather
- * than leaving a plaintext copy behind that would keep winning. If no default
- * workspace exists anywhere (ours or the reference CLI's), this slug becomes it.
+ * than leaving a plaintext copy behind that would keep winning. Global defaults
+ * are only written by setDefaultWorkspace; existing legacy defaults are preserved.
  */
 export function writeCredential(
   slug: string,
@@ -1122,12 +1174,6 @@ export function writeCredential(
     }
     systemBackend?.delete(oauthAccount(slug));
     ws[slug] = table;
-    if (!asString(obj.default_workspace)) {
-      // Leave the reference CLI's default in charge if it has one; writing ours
-      // over it would silently switch a migrating user's workspace.
-      const reference = readReferenceCredentials(referenceCredentialsPath());
-      if (!reference.defaultWorkspace) obj.default_workspace = slug;
-    }
     writeUserObject(path, obj);
     return { path, storage, keyringLabel: backend?.label };
   });
@@ -1151,6 +1197,31 @@ export function setDefaultWorkspace(slug: string): string {
   });
 }
 
+/** Set non-secret team metadata on one existing workspace profile. */
+export function setWorkspaceTeam(
+  slug: string,
+  team: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const path = userConfigPath(env);
+  return withUserConfigLock(path, () => {
+    const known = readUserConfig(path).workspaces;
+    if (!known[slug]) {
+      throw new CliError(
+        `Workspace '${sanitize(slug)}' is not configured. Run \`linear auth login --workspace ${sanitize(slug)}\` first.`,
+        "not_found",
+      );
+    }
+    const obj = readUserObject(path);
+    const ws = workspacesTable(obj);
+    const table: WorkspaceTable = { ...(ws[slug] ?? {}) };
+    table.team = team;
+    ws[slug] = table;
+    writeUserObject(path, obj);
+    return path;
+  });
+}
+
 /**
  * Drop `slug` from the reference CLI's keyring-format credentials list, if it
  * is there, in that file's own layout (`default` first, sorted `workspaces`).
@@ -1162,7 +1233,7 @@ function removeFromReferenceCredentials(slug: string): boolean {
   const reference = readReferenceCredentials(path);
   if (!reference.workspaces.includes(slug)) return false;
   const workspaces = reference.workspaces.filter((s) => s !== slug).sort();
-  const def = reference.defaultWorkspace === slug ? workspaces[0] : reference.defaultWorkspace;
+  const def = reference.defaultWorkspace === slug ? undefined : reference.defaultWorkspace;
   const obj: Record<string, unknown> = {};
   if (def) obj.default = def;
   obj.workspaces = workspaces;
@@ -1173,13 +1244,20 @@ function removeFromReferenceCredentials(slug: string): boolean {
 /**
  * Forget a workspace: remove its `[workspaces."<slug>"]` table, its keyring
  * entry, and its line in the reference CLI's list — whichever exist. If the
- * removed slug was the default, the default is repointed to a remaining
- * workspace (or cleared). Returns true if anything was removed.
+ * removed slug was the default, that default is cleared without choosing another
+ * workspace. Returns true if anything was removed.
  */
-export function removeCredential(slug: string): boolean {
+export interface RemoveCredentialResult {
+  removed: boolean;
+  teamMetadataRemoved: boolean;
+}
+
+/** Detailed removal receipt used by `auth logout`. */
+export function removeCredentialWithMetadata(slug: string): RemoveCredentialResult {
   const path = userConfigPath();
   return withUserConfigLock(path, () => {
     let removed = false;
+    let teamMetadataRemoved = false;
 
     const backend = keyring();
     if (backend) {
@@ -1188,31 +1266,36 @@ export function removeCredential(slug: string): boolean {
     }
     if (removeFromReferenceCredentials(slug)) removed = true;
 
-    if (!existsSync(path)) return removed;
+    if (!existsSync(path)) return { removed, teamMetadataRemoved };
     const obj = readUserObject(path);
     const ws = workspacesTable(obj);
     const listed = Boolean(ws[slug]);
     if (listed) {
+      teamMetadataRemoved = asString(ws[slug]?.team) !== undefined;
       delete ws[slug];
       removed = true;
     }
     if (Object.keys(ws).length === 0) delete obj.workspaces;
 
     if (asString(obj.default_workspace) === slug) {
-      const remaining = obj.workspaces ? Object.keys(obj.workspaces as object) : [];
-      if (remaining.length > 0) obj.default_workspace = remaining[0]!;
-      else delete obj.default_workspace;
+      delete obj.default_workspace;
       writeUserObject(path, obj);
     } else if (listed) {
       writeUserObject(path, obj);
     }
-    return removed;
+    return { removed, teamMetadataRemoved };
   });
 }
 
+/** Backward-compatible boolean removal API. */
+export function removeCredential(slug: string): boolean {
+  return removeCredentialWithMetadata(slug).removed;
+}
+
 export interface RemoveOAuthCredentialResult {
   removed: boolean;
   fallbackCredentialType: "api-key" | null;
+  teamMetadataRemoved: boolean;
 }
 
 /** Remove only the human OAuth lifecycle, restoring a pre-existing API-key profile if present. */
@@ -1223,6 +1306,7 @@ export function removeOAuthCredential(slug: string): RemoveOAuthCredentialResult
     let oauthRaw: string | null = null;
     let keyringApiKey = false;
     let removed = false;
+    let teamMetadataRemoved = false;
     if (backend) {
       try {
         oauthRaw = backend.get(oauthAccount(slug));
@@ -1237,7 +1321,11 @@ export function removeOAuthCredential(slug: string): RemoveOAuthCredentialResult
     }
 
     if (!existsSync(path)) {
-      return { removed, fallbackCredentialType: keyringApiKey ? "api-key" : null };
+      return {
+        removed,
+        fallbackCredentialType: keyringApiKey ? "api-key" : null,
+        teamMetadataRemoved,
+      };
     }
     try {
       const obj = readUserObject(path);
@@ -1245,7 +1333,6 @@ export function removeOAuthCredential(slug: string): RemoveOAuthCredentialResult
       const table = ws[slug];
       const hadOAuthMarker = table?.oauth === true;
       if (hadOAuthMarker) removed = true;
-      const reference = readReferenceCredentials(referenceCredentialsPath());
       const apiKeyFallback = Boolean(asString(table?.api_key)) || keyringApiKey;
 
       if (apiKeyFallback) {
@@ -1255,21 +1342,19 @@ export function removeOAuthCredential(slug: string): RemoveOAuthCredentialResult
         else fallback.keyring = true;
         ws[slug] = fallback;
       } else if (table) {
+        teamMetadataRemoved = asString(table.team) !== undefined;
         delete ws[slug];
       }
       if (Object.keys(ws).length === 0) delete obj.workspaces;
 
       if (!apiKeyFallback && asString(obj.default_workspace) === slug) {
-        const remaining = obj.workspaces ? Object.keys(obj.workspaces as object) : [];
-        const referenceFallback = reference.workspaces.find((candidate) => candidate !== slug);
-        if (remaining.length > 0) obj.default_workspace = remaining[0]!;
-        else if (referenceFallback) obj.default_workspace = referenceFallback;
-        else delete obj.default_workspace;
+        delete obj.default_workspace;
       }
       if (hadOAuthMarker || apiKeyFallback) writeUserObject(path, obj);
       return {
         removed,
         fallbackCredentialType: apiKeyFallback ? "api-key" : null,
+        teamMetadataRemoved,
       };
     } catch (err) {
       try {

package/src/context.ts

@@ -7,6 +7,7 @@
 import type { LinearClient } from "@linear/sdk";
 import { resolveConfig, type ResolvedConfig } from "./config.js";
 import { createClient, setRetryReporter } from "./client.js";
+import { promptSelect } from "./lib/prompt.js";
 import { Output } from "./output/format.js";
 import { isDebugEnabled, shouldUseColor } from "./output/color.js";
 
@@ -46,7 +47,7 @@ export function firstTeam(team: string | string[] | undefined): string | undefin
 }
 
 export class Context {
-  readonly config: ResolvedConfig;
+  config: ResolvedConfig;
   readonly output: Output;
   readonly options: GlobalOptions;
   readonly isTTY: boolean;
@@ -96,6 +97,25 @@ export class Context {
     setRetryReporter((line) => this.output.info(line));
   }
 
+  /** Choose only for this invocation; never persist an interactive fallback. */
+  async selectWorkspace(): Promise<void> {
+    const choices = this.config.workspaceChoices;
+    if (!choices || !this.isTTY) return;
+    const workspace = await promptSelect(
+      this,
+      "Select a workspace for this invocation",
+      choices.map((slug) => ({ name: slug, value: slug })),
+    );
+    this.config = resolveConfig({
+      flags: {
+        apiKey: this.options.apiKey,
+        accessToken: this.options.accessToken,
+        team: firstTeam(this.options.team),
+        workspace,
+      },
+    });
+  }
+
   /** Lazily construct the Linear client (so `--help` never needs a key). */
   get client(): LinearClient {
     if (!this._client) this._client = createClient(this.config);

package/src/lib/action.ts

@@ -21,6 +21,14 @@ export function action(handler: ActionHandler) {
     const localOpts = (args[args.length - 2] ?? {}) as Record<string, any>;
     const positionals = args.slice(0, -2);
     const ctx = new Context(command.optsWithGlobals() as GlobalOptions);
+    // Repair and local discovery need no selection. Config/open select within
+    // their handlers only when the chosen path needs credentials.
+    let group = command;
+    while (group.parent?.parent) group = group.parent;
+    const offline =
+      ["config", "open", "commands", "completion"].includes(group.name()) ||
+      (group.name() === "auth" && !["whoami", "status", "token"].includes(command.name()));
+    if (!offline) await ctx.selectWorkspace();
     await handler(ctx, localOpts, ...positionals);
   };
 }

package/src/lib/delegation.ts

@@ -0,0 +1,240 @@
+/**
+ * Linear for Agents (Developer Preview) helpers.
+ *
+ * Delegates are deliberately resolved separately from assignees. A human can
+ * own an issue; only an active, assignable app user with access to the issue's
+ * team can be delegated the work.
+ */
+
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { CliError, ambiguous, normalizeError, notFound } from "./errors.js";
+import { isUuid } from "./resolve.js";
+
+const PAGE_SIZE = 250;
+const SCAN_CAP = 2000;
+const MAX_LISTED = 25;
+
+export interface DelegateRef {
+  id: string;
+  displayName: string;
+  name: string;
+}
+
+function delegationMessages(err: unknown): { normalized: CliError; messages: string } {
+  const normalized = normalizeError(err);
+  return {
+    normalized,
+    messages: [normalized.message, JSON.stringify(normalized.detail ?? "")].join(" "),
+  };
+}
+
+function missingDelegationSchema(messages: string): boolean {
+  return (
+    /(cannot query field|unknown (argument|field)|is not defined by type).*(delegate|isAssignable|canAccessAnyPublicTeam)/i.test(
+      messages,
+    ) ||
+    /(delegateId|delegate|isAssignable|canAccessAnyPublicTeam).*(cannot query field|unknown (argument|field)|is not defined by type)/i.test(
+      messages,
+    )
+  );
+}
+
+/** Whether an issue read can safely retry without its one preview-only field. */
+export function isDelegationReadUnavailable(err: unknown): boolean {
+  const { normalized, messages } = delegationMessages(err);
+  return (
+    missingDelegationSchema(messages) ||
+    (normalized.code === "feature_not_accessible" && /delegate/i.test(messages))
+  );
+}
+
+interface DelegateCandidate extends DelegateRef {
+  active: boolean;
+  app: boolean;
+  isAssignable: boolean;
+  canAccessAnyPublicTeam: boolean;
+  teams: { nodes: Array<{ id: string }> };
+}
+
+const CANDIDATE_FIELDS = `
+  id displayName name active app isAssignable canAccessAnyPublicTeam
+  teams(filter: { id: { eq: $teamId } }, first: 1) { nodes { id } }
+`;
+
+const CANDIDATES_QUERY = `
+query CliDelegateCandidates($teamId: String!, $after: String) {
+  users(first: ${PAGE_SIZE}, after: $after, includeDisabled: true, includeArchived: true) {
+    nodes { ${CANDIDATE_FIELDS} }
+    pageInfo { hasNextPage endCursor }
+  }
+}
+`;
+
+const CANDIDATE_QUERY = `
+query CliDelegateCandidate($id: String!, $teamId: String!) {
+  user(id: $id) { ${CANDIDATE_FIELDS} }
+}
+`;
+
+/**
+ * Turn an unavailable Developer Preview schema/feature into a stable boundary.
+ * Other validation failures retain their original code and wording.
+ */
+export function delegationFeatureError(err: unknown): CliError {
+  const { normalized, messages } = delegationMessages(err);
+  const schemaMissing = missingDelegationSchema(messages);
+  if (normalized.code !== "feature_not_accessible" && !schemaMissing) return normalized;
+  return new CliError(
+    "Issue delegation is unavailable in this Linear workspace or API schema (Linear for Agents is in Developer Preview).",
+    "feature_not_accessible",
+    normalized.detail,
+    "Enable an assignable agent integration with access to this team, or retry when the workspace supports issue delegation.",
+  );
+}
+
+async function request<T>(client: LinearClient, query: string, variables: object): Promise<T> {
+  try {
+    const response: any = await withRetry(() =>
+      (client as any).client.rawRequest(query, variables),
+    );
+    return response.data as T;
+  } catch (err) {
+    throw delegationFeatureError(err);
+  }
+}
+
+async function allCandidates(client: LinearClient, teamId: string): Promise<DelegateCandidate[]> {
+  const candidates: DelegateCandidate[] = [];
+  let after: string | undefined;
+  for (;;) {
+    const data = await request<{
+      users: {
+        nodes: DelegateCandidate[];
+        pageInfo: { hasNextPage: boolean; endCursor: string | null };
+      };
+    }>(client, CANDIDATES_QUERY, { teamId, after });
+    candidates.push(...data.users.nodes);
+    if (!data.users.pageInfo.hasNextPage) return candidates;
+    if (candidates.length >= SCAN_CAP || !data.users.pageInfo.endCursor) {
+      throw new CliError(
+        `More than ${SCAN_CAP} workspace users to search; pass the agent user UUID instead.`,
+        "usage",
+      );
+    }
+    after = data.users.pageInfo.endCursor;
+  }
+}
+
+function isBaseEligible(candidate: DelegateCandidate): boolean {
+  return candidate.active && candidate.app && candidate.isAssignable;
+}
+
+function hasTeamAccess(candidate: DelegateCandidate, privateTeam: boolean): boolean {
+  return candidate.teams.nodes.length > 0 || (!privateTeam && candidate.canAccessAnyPublicTeam);
+}
+
+function label(candidate: DelegateCandidate): string {
+  const names =
+    candidate.displayName === candidate.name
+      ? candidate.displayName
+      : `${candidate.displayName} (${candidate.name})`;
+  return `${names} [${candidate.id}]`;
+}
+
+function validateCandidate(
+  candidate: DelegateCandidate,
+  team: { key: string; private: boolean },
+): DelegateRef {
+  if (!candidate.active) {
+    throw new CliError(
+      `'${candidate.displayName}' is inactive and cannot be delegated issues.`,
+      "validation",
+    );
+  }
+  if (!candidate.app) {
+    throw new CliError(
+      `'${candidate.displayName}' is a human user. Use --assignee for people; --delegate accepts agent app users only.`,
+      "validation",
+    );
+  }
+  if (!candidate.isAssignable) {
+    throw new CliError(
+      `'${candidate.displayName}' is an app user but is not eligible for issue delegation.`,
+      "validation",
+      undefined,
+      "Reinstall or reconfigure the agent with Linear's app:assignable scope.",
+    );
+  }
+  if (!hasTeamAccess(candidate, team.private)) {
+    throw new CliError(
+      `'${candidate.displayName}' cannot access team ${team.key} and cannot be delegated this issue.`,
+      "validation",
+      undefined,
+      "Ask a Linear workspace admin to grant the agent access to this team.",
+    );
+  }
+  return { id: candidate.id, displayName: candidate.displayName, name: candidate.name };
+}
+
+/**
+ * Resolve an agent by UUID, exact display name, or exact full name. Exact case
+ * wins over case-insensitive matching; ambiguity considers eligible app users
+ * only and lists safe names plus IDs.
+ */
+export async function resolveDelegate(
+  client: LinearClient,
+  input: string,
+  teamId: string,
+): Promise<DelegateRef> {
+  let team: { key: string; private: boolean };
+  try {
+    const model: any = await withRetry(() => client.team(teamId));
+    team = { key: model.key, private: !!model.private };
+  } catch (err) {
+    throw delegationFeatureError(err);
+  }
+
+  if (isUuid(input)) {
+    const data = await request<{ user: DelegateCandidate | null }>(client, CANDIDATE_QUERY, {
+      id: input,
+      teamId,
+    });
+    if (!data.user) throw notFound(`No agent user with id '${input}'.`);
+    return validateCandidate(data.user, team);
+  }
+
+  const candidates = await allCandidates(client, teamId);
+  const exact = candidates.filter(
+    (candidate) => candidate.displayName === input || candidate.name === input,
+  );
+  const lower = input.toLocaleLowerCase();
+  const matching = exact.length
+    ? exact
+    : candidates.filter(
+        (candidate) =>
+          candidate.displayName.toLocaleLowerCase() === lower ||
+          candidate.name.toLocaleLowerCase() === lower,
+      );
+  const eligible = matching.filter(
+    (candidate) => isBaseEligible(candidate) && hasTeamAccess(candidate, team.private),
+  );
+  if (eligible.length > 1) {
+    throw ambiguous(
+      `Multiple eligible agents match '${input}': ${eligible.map(label).join(", ")}. Pass the agent user UUID.`,
+    );
+  }
+  if (eligible.length === 1) return validateCandidate(eligible[0]!, team);
+  if (matching.length > 0) return validateCandidate(matching[0]!, team);
+
+  const available = candidates.filter(
+    (candidate) => isBaseEligible(candidate) && hasTeamAccess(candidate, team.private),
+  );
+  const suffix =
+    available.length === 0
+      ? " No eligible agents can access this team."
+      : available.length > MAX_LISTED
+        ? ` Run 'linear user list --all' to inspect workspace users.`
+        : ` Available agents: ${available.map(label).join(", ")}.`;
+  throw notFound(`No eligible agent matching '${input}'.${suffix}`);
+}