ticketlens 0.40.1 → 0.42.0

package/README.md

@@ -499,7 +499,7 @@ Write directly to the ticket in its real tracker — Jira, GitHub, or Linear —
 
 `ticketlens transition` with just a ticket key lists the tracker's current valid options without changing anything (Jira: real workflow transitions for that issue; GitHub: open/closed; Linear: team-scoped workflow states). Add both `--target` and `--confirm` to execute — `--confirm` is a deliberate two-step gate: a behavioral nudge and forensic trail, not a hard security guarantee. Every write, once resolved, is re-validated against the tracker's current state immediately before executing — never a blind write against a stale option.
 
-`ticketlens assign` is self-assign only for now — `--to` must be `me`. Assigning to someone else needs a per-tracker user-lookup step this doesn't do yet, so it's deliberately out of scope until that's built.
+`ticketlens assign --to=me` self-assigns immediately, no `--confirm` needed. Any other `--to` (a name or email) assigns to another developer — Jira Cloud only for now, GitHub/Linear/Server-DC refuse cleanly. It searches Jira's real assignable-user list first: without `--confirm` it only lists the matching candidate(s), never assigns; with `--confirm` it executes only if exactly one candidate still matches (0 or 2+ always refuses). Matches are cached locally per project for 3 days.
 
 `ticketlens worklog` (or `tl worklog`) logs time on Jira tickets, always as you.
 
@@ -1121,6 +1121,7 @@ npm test
 See [ROADMAP.md](ROADMAP.md) for the full plan.
 
 Recently shipped:
+- **`ticketlens assign --to="name or email"`** — assign a ticket to another developer, not just yourself. Jira Cloud only for now; searches real assignable users first, lists matches, executes only on one confirmed match. Pro tier
 - **Console: Recall "select all N matching" bulk delete** — Gmail-style banner deletes every note matching your search/filters across all pages, not just the current one
 - **Recall Stop-hook fix** — the end-of-session Recall reminder no longer fires because of file writes; only real ticket writes (comment, transition, assign, update) arm it. Also hardened against malformed transcripts and a session-id path-collision bug found by adversarial testing
 - **Console: no repeat request on same-page menu clicks** — sidebar links, the header gear and Settings tabs skip the request when they point at the page you are on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.40.1",
+  "version": "0.42.0",
   "description": "Jira CLI for developers — fetch ticket context, triage your queue, and stop tab-switching. Zero dependencies, all local.",
   "type": "module",
   "bin": {

package/skills/jtb/SKILL.md

@@ -1,4 +1,4 @@
-<!-- jtb-skill-version: 0.45.0 -->
+<!-- jtb-skill-version: 0.46.0 -->
 ---
 name: jtb
 description: Fetch a Jira ticket's full context (description, comments, linked issues, code references) and assemble a structured TicketBrief for implementation planning. Use when user types /jtb, mentions a Jira ticket key, or wants to plan work from a Jira ticket.
@@ -436,7 +436,9 @@ ticketlens comment PROD-1234 --body="Fixed in a2f9c1, deployed to staging."
 ticketlens comment PROD-1234 --body="See screenshot" --attach=./bug.png  # attach local files
 ticketlens transition PROD-1234                              # list valid transitions — read-only
 ticketlens transition PROD-1234 --target="Done" --confirm    # execute
-ticketlens assign PROD-1234 --to=me                          # assign to yourself
+ticketlens assign PROD-1234 --to=me                          # assign to yourself — immediate, no --confirm
+ticketlens assign PROD-1234 --to="Jane Dev"                  # search assignable users — read-only, lists match(es)
+ticketlens assign PROD-1234 --to="Jane Dev" --confirm        # execute — only if exactly one match (Jira Cloud only)
 ticketlens duplicates PROD-1234                               # find likely duplicates — read-only
 ticketlens link PROD-1234 PROD-5678                            # list valid link types — read-only
 ticketlens link PROD-1234 PROD-5678 --type="Duplicate" --confirm  # execute the link
@@ -451,13 +453,13 @@ ticketlens worklog PROD-1234=1h30m PROD-5678=45m --comment="Sprint work" --confi
 
 `transition` called with just a ticket key never mutates anything — it lists the tracker's current valid options (Jira: real workflow transitions for that issue; GitHub: open/closed; Linear: team-scoped workflow states). Only add `--target` **and** `--confirm` once the target has actually been confirmed with the user — `--confirm` is a deliberate two-step gate, not a formality to route around. Never guess a `--target` value; always list first, then use one of the names shown.
 
-`assign` is self-assign only — `--to` must be `me`. There is no way to assign to anyone else yet; don't attempt a workaround (e.g. via `comment`) if the user asks for that — tell them it isn't supported.
+`assign` — `--to=me` self-assigns immediately, no `--confirm` needed. Any other `--to` (a name or email) assigns to another developer, Jira Cloud only for now — GitHub, Linear, and Jira Server/DC refuse cleanly rather than guess at unverified API behavior. It searches Jira's real assignable-user list first: called without `--confirm` it never assigns, only lists the matching candidate(s) (name + accountId, cached locally per project for 3 days); called again with the same `--to` and `--confirm`, it executes only if exactly one candidate still matches — 0 or 2+ matches always refuses, never guesses which person was meant. Never attempt a workaround (e.g. via `comment`) for a tracker `assign` refuses (GitHub/Linear/Server-DC) — tell the user it isn't supported yet.
 
 `duplicates` lists likely-duplicate tickets in the same project. On Jira, any ticket already linked as a "Duplicate" is always listed first — that's a confirmed relationship a human already recorded, not a heuristic. Everything else is ranked by local title/description overlap — no tracker scores similarity server-side, so treat those as a nudge for the user to check manually, never as a confirmed duplicate to act on unprompted (e.g. don't auto-close or auto-comment based on a match). `--threshold=N` (0–1, default 0.35) tightens or loosens what counts as a text-match — it has no effect on Jira-linked duplicates, which are always shown. An empty result is the same approximation in the other direction — the local scorer can miss a real duplicate too, so don't treat "no likely duplicates found" as proof none exist.
 
 `link SOURCE-KEY TARGET-KEY` links two tickets — direction matters: SOURCE "types" TARGET (e.g. `link A B --type=Duplicate` means A duplicates B, not the other way around). Called with just the two keys, it lists the tracker's current valid link types without changing anything — never guess `--type`; always list first, then use one of the names shown. GitHub has no generic link relationship, so linking on a GitHub-tracked ticket *closes SOURCE as a duplicate of TARGET* — a real state change, not just a relationship add — and prints an explicit warning immediately before that happens, on top of the same `--confirm` gate.
 
-`update TICKET-KEY` updates a narrow, named field set — title, description, labels, priority. At least one field is required. Labels are always add/remove (`--add-labels=a,b` / `--remove-labels=c`), never a wholesale replace — an unnamed existing label is left alone, never silently dropped. No `--confirm` needed — these are reversible metadata edits, same risk tier as `assign`.
+`update TICKET-KEY` updates a narrow, named field set — title, description, labels, priority. At least one field is required. Labels are always add/remove (`--add-labels=a,b` / `--remove-labels=c`), never a wholesale replace — an unnamed existing label is left alone, never silently dropped. No `--confirm` needed — these are reversible metadata edits, same risk tier as self-assign.
 
 `create` makes a brand-new ticket — there's no existing ticket to target, so `--project` (Jira project key / Linear team key) and `--type` (Jira issue type, ignored elsewhere) pick the destination instead of a ticket key. This is the highest-blast-radius command in the family: a bad `--project`/`--type` fabricates a real, hard-to-walk-back item in a live tracker. No `--confirm` gate — double-check the values with the user before calling it, since an invalid value surfaces the tracker's own error rather than a silent guess.
 

package/skills/jtb/scripts/lib/adapters/jira-adapter.mjs

@@ -1,4 +1,4 @@
-import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses, fetchProjects, fetchIssueTypes, postComment, getTransitions, postTransition, assignIssue, escapeJql, getIssueLinkTypes, postIssueLink, updateIssue, createIssue, DEFAULT_SEARCH_FIELDS } from '../jira-client.mjs';
+import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses, fetchProjects, fetchIssueTypes, fetchProjectPriorities, postComment, getTransitions, postTransition, assignIssue, fetchAssignableUsers, escapeJql, getIssueLinkTypes, postIssueLink, updateIssue, createIssue, DEFAULT_SEARCH_FIELDS } from '../jira-client.mjs';
 import { postWorklog } from '../jira-worklog-client.mjs';
 import { uploadAttachment, resolveMediaId } from '../jira-attachment-client.mjs';
 import { readAttachments } from '../attachment-uploader.mjs';
@@ -83,6 +83,31 @@ export function createJiraAdapter(conn, { fetcher = globalThis.fetch } = {}) {
       return { assignee: me.displayName ?? value };
     },
 
+    /**
+     * Resolves a free-text name/email into candidate assignable users —
+     * read-only, never assigns. Cloud only (`apiVersion === 3`): Jira
+     * Server/DC's equivalent endpoint semantics are unverified, so this
+     * refuses rather than guess at request/response shape (ROADMAP 61).
+     * Caching (3-day TTL, per project+query) is the caller's job — same
+     * split as `listIssueTypes`, which is also cache-agnostic here.
+     */
+    async searchAssignableUsers(key, query, opts = {}) {
+      if (apiVersion !== 3) {
+        throw new Error('Assigning to another developer needs Jira Cloud — Server/DC is not supported yet.');
+      }
+      const users = await fetchAssignableUsers(key, query, { ...base, ...opts });
+      return users.map(u => ({ accountId: u.accountId, displayName: u.displayName ?? u.name ?? u.accountId }));
+    },
+
+    /**
+     * Executes an assignment to a resolved accountId — always Cloud
+     * (`searchAssignableUsers` is the only path that produces one), so no
+     * apiVersion branch is needed here the way `assignToSelf` has.
+     */
+    async assignToUser(key, accountId, opts = {}) {
+      await assignIssue(key, { accountId }, { ...base, ...opts });
+    },
+
     /**
      * Candidate search for duplicate-ticket detection. Scoped to the same
      * project as `sourceKey` (derived from its own prefix) and excludes it
@@ -186,6 +211,34 @@ export function createJiraAdapter(conn, { fetcher = globalThis.fetch } = {}) {
     /** Real, currently-configured issue types for one project. */
     listIssueTypes: (projectKey, opts = {}) => fetchIssueTypes(projectKey, { ...base, ...opts }),
 
+    /**
+     * Real, currently-configured priority options for one project — used
+     * only to enrich an `update` failure message, never to pre-validate
+     * (see fetchProjectPriorities' own doc for why). Priority has no
+     * dedicated list-per-project endpoint, so this walks the project's
+     * issue types until one returns a non-empty priority list. NOT every
+     * issue type has one: confirmed live against corenexus that a
+     * team-managed project's Epic type has no `priority` field in its
+     * field metadata at all (real fields returned: assignee, description,
+     * labels, ... — priority absent), while its Task type does. An
+     * earlier version picked types[0] unconditionally and silently
+     * returned [] whenever that happened to be an Epic — caught by a live
+     * CLI run against CNV1-34, not by any unit test (every unit test used
+     * a hand-picked type). Stops at the first success rather than trying
+     * every type, since priority is otherwise scheme-shared across a
+     * project's types by Jira's default. Returns [] only once every type
+     * has been tried — this can only ever make an error message less
+     * informative, never a new way for `update` to fail.
+     */
+    async listPriorities(projectKey, opts = {}) {
+      const types = await fetchIssueTypes(projectKey, { ...base, ...opts });
+      for (const type of types) {
+        const priorities = await fetchProjectPriorities(projectKey, type.id, { ...base, ...opts });
+        if (priorities.length) return priorities;
+      }
+      return [];
+    },
+
     /**
      * Best-effort, per-file: one bad path or one failed upload never blocks
      * the rest (same `{applied/uploaded, errors}` shape convention as

package/skills/jtb/scripts/lib/adapters/linear-adapter.mjs

@@ -1,6 +1,7 @@
 import { tokenize } from '../duplicate-scorer.mjs';
 import { readAttachments } from '../attachment-uploader.mjs';
 import { isSafeRedirectUrl, validateResolvedHost, defaultLookupFor } from '../jira-client.mjs';
+import { SINGLE_PROJECT_TTL_MS, isFresh, mergeTeamLabels } from '../ticket-metadata-cache.mjs';
 
 const LINEAR_API = 'https://api.linear.app/graphql';
 
@@ -103,6 +104,22 @@ function resolveLabelNames(names, byName) {
   return { resolved, missing };
 }
 
+/**
+ * Real, currently-configured labels for one team — extracted from
+ * updateFields' own inline query so the cache read-through wrapper around
+ * it (see updateFields below) and this raw fetch stay independently
+ * testable. Returns {id, name} to match ticket-metadata-cache.mjs's
+ * documented labelsByTeam shape exactly.
+ */
+async function fetchTeamLabels(teamId, { token, fetcher, signal }) {
+  const data = await gql(
+    `query ($teamId: ID!) { issueLabels(filter: { team: { id: { eq: $teamId } } }, first: 250) { nodes { id name } } }`,
+    { teamId },
+    { token, fetcher, signal },
+  );
+  return (data.issueLabels?.nodes ?? []).map(l => ({ id: l.id, name: l.name }));
+}
+
 async function fetchTeamWorkflowStates(teamId, { token, fetcher, signal }) {
   const data = await gql(
     `query ($teamId: ID!) {
@@ -393,12 +410,28 @@ export function createLinearAdapter(conn, { fetcher = globalThis.fetch } = {}) {
 
       let addLabelsResolved, addLabelsMissing, removeLabelsResolved, removeLabelsMissing;
       if (addLabels?.length || removeLabels?.length) {
-        const labelData = await gql(
-          `query ($teamId: ID!) { issueLabels(filter: { team: { id: { eq: $teamId } } }, first: 250) { nodes { id name } } }`,
-          { teamId: info.team.id },
-          { token, fetcher, signal },
-        );
-        const byName = new Map((labelData.issueLabels?.nodes ?? []).map(l => [l.name.toLowerCase(), l.id]));
+        const teamId = info.team.id;
+        const { readMetadataCacheFn, writeMetadataCacheFn, profileName, configDir } = opts;
+        const cached = readMetadataCacheFn ? readMetadataCacheFn(profileName, configDir) : null;
+        // Keyed on the timestamp existing, not on the cached array having
+        // entries — a team with genuinely zero labels configured caches
+        // `[]`, and gating on `.length` would re-fetch on every single
+        // subsequent call, never respecting SINGLE_PROJECT_TTL_MS. Same
+        // fix as ticket-update-enrichment.mjs's prioritiesByProject check.
+        const hasFreshLabels = cached?.labelsByTeam?.[teamId] !== undefined
+          && isFresh(cached?.labelsFetchedAt?.[teamId], SINGLE_PROJECT_TTL_MS);
+
+        let labels;
+        if (hasFreshLabels) {
+          labels = cached.labelsByTeam[teamId];
+        } else {
+          labels = await fetchTeamLabels(teamId, { token, fetcher, signal });
+          if (writeMetadataCacheFn) {
+            const { labelsByTeam, labelsFetchedAt } = mergeTeamLabels(cached, teamId, labels);
+            writeMetadataCacheFn(profileName, { ...cached, labelsByTeam, labelsFetchedAt }, configDir);
+          }
+        }
+        const byName = new Map(labels.map(l => [l.name.toLowerCase(), l.id]));
 
         if (addLabels?.length) {
           ({ resolved: addLabelsResolved, missing: addLabelsMissing } = resolveLabelNames(addLabels, byName));

package/skills/jtb/scripts/lib/help.mjs

@@ -670,7 +670,9 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     `  ${s.cyan('issue_types')} is Free and Jira-only — Linear/GitHub profiles get a clear`,
     `  "not available" instead of an empty result — every other tool needs Pro.`,
     `  ${s.cyan('ticket_transition')} is destructive when called with`,
-    `  \`target\`+\`confirm: true\`; ${s.cyan('ticket_assign')} is currently self-assign only;`,
+    `  \`target\`+\`confirm: true\`; ${s.cyan('ticket_assign')}'s \`to: "me"\` self-assigns immediately,`,
+    `  no confirm needed — assigning to another developer (Jira Cloud only) resolves`,
+    `  \`to\` first and needs \`confirm: true\` once it matches exactly one candidate;`,
     `  ${s.cyan('ticket_worklog')} is Jira-only, logs as you only, and writes nothing without`,
     `  \`confirm: true\` (it previews instead) — a worklog cannot be deleted through TicketLens;`,
     `  ${s.cyan('ticket_duplicates')} is read-only; ${s.cyan('ticket_link')} on GitHub closes the source issue as a`,
@@ -778,19 +780,26 @@ export function printAssignHelp({ stream = process.stdout } = {}) {
     '',
     `  ${s.bold(s.brand('ticketlens'))} ${s.bold('assign')} ${s.dim('TICKET-KEY --to=me')}  ${s.dim('[Pro]')}`,
     '',
-    `  Assign a ticket to yourself directly in its tracker (Jira/GitHub/Linear). ${s.dim('[Pro]')}`,
-    `  Self-assign only for now — ${s.brand('--to')} must be ${s.brand('me')}. Assigning to someone else`,
-    `  isn't supported yet.`,
+    `  Assign a ticket directly in its tracker (Jira/GitHub/Linear). ${s.dim('[Pro]')}`,
+    `  ${s.brand('--to=me')} self-assigns immediately, no --confirm needed. Any other`,
+    `  ${s.brand('--to')} (a name or email) assigns to another developer — Jira Cloud`,
+    `  only for now. Resolves the name/email against real assignable users first:`,
+    `  without --confirm it lists the match(es) instead of assigning; with`,
+    `  --confirm it executes only if exactly one candidate matched. Results are`,
+    `  cached locally per project for 3 days.`,
     '',
     `  ${s.bold('OPTIONS')}`,
     '',
-    `    ${s.brand('--to')}=${s.dim('me')}       Required — only "me" is currently supported`,
-    `    ${s.brand('--profile')}=${s.dim('NAME')} Connection profile to use ${s.dim('(optional)')}`,
-    `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
+    `    ${s.brand('--to')}=${s.dim('me|"name or email"')}  Required`,
+    `    ${s.brand('--confirm')}        Execute an assign-to-other match ${s.dim('(not needed for --to=me)')}`,
+    `    ${s.brand('--profile')}=${s.dim('NAME')}    Connection profile to use ${s.dim('(optional)')}`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}      Show this help`,
     '',
     `  ${s.bold('EXAMPLES')}`,
     '',
     `    ${s.dim('$')} ticketlens assign PROD-123 --to=me`,
+    `    ${s.dim('$')} ticketlens assign PROD-123 --to="Jane Dev"`,
+    `    ${s.dim('$')} ticketlens assign PROD-123 --to="Jane Dev" --confirm`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');

package/skills/jtb/scripts/lib/jira-client.mjs

@@ -613,6 +613,39 @@ export async function assignIssue(ticketKey, assignee, opts = {}) {
   }
 }
 
+/**
+ * Searches for users assignable to a ticket — resolves a caller-typed
+ * name/email into a real accountId before assignIssue can use it.
+ *
+ * `query` is required by Jira's own API: `GET .../user/assignable/search`
+ * 400s unless `query` or `accountId` is given (verified against Atlassian's
+ * published spec — there is no "list everyone assignable" mode), so this
+ * throws early on an empty query rather than sending a request guaranteed
+ * to fail.
+ */
+export async function fetchAssignableUsers(ticketKey, query, opts = {}) {
+  const { env = process.env, fetcher = globalThis.fetch, lookup = defaultLookupFor(fetcher), apiVersion = 2, timeoutMs = 10_000, allowPrivateIp = false, maxResults = 20 } = opts;
+  if (!query) {
+    throw new Error('fetchAssignableUsers requires a non-empty query — Jira has no "list all assignable users" mode.');
+  }
+  validateBaseUrl(env.JIRA_BASE_URL, allowPrivateIp);
+  const baseUrl = env.JIRA_BASE_URL.replace(/\/$/, '');
+  const params = new URLSearchParams({ issueKey: ticketKey, query, maxResults: String(maxResults) });
+  const url = `${baseUrl}/rest/api/${apiVersion}/user/assignable/search?${params}`;
+
+  const fetchOpts = { headers: { ...buildAuthHeader(env), 'Content-Type': 'application/json' } };
+  if (timeoutMs) fetchOpts.signal = AbortSignal.timeout(timeoutMs);
+
+  const response = await guardedFetch(url, fetchOpts, { fetcher, lookup, allowPrivateIp });
+  if (!response.ok) {
+    const err = new Error(`Jira API error ${response.status} searching assignable users for ${ticketKey}`);
+    err.status = response.status;
+    throw err;
+  }
+  const raw = await response.json();
+  return raw.map(u => ({ accountId: u.accountId ?? null, name: u.name ?? null, displayName: u.displayName ?? null }));
+}
+
 /**
  * Updates a narrow, named field set on an issue. `fields` (summary,
  * description, priority) uses plain SET semantics — the same shape Jira's
@@ -705,6 +738,46 @@ export async function fetchIssueTypes(projectKey, opts = {}) {
   return values.map(t => ({ id: t.id, name: t.name }));
 }
 
+/**
+ * Discovers the priority scheme actually configured for a project — used
+ * only to enrich an `update` failure message with real, current options,
+ * never as a client-side pre-validation step (same design choice as
+ * fetchIssueTypes' own doc comment). Confirmed live against a Cloud
+ * instance (corenexus) and a Server/DC instance (advent) that a project's
+ * priority list lives on this per-issuetype field-metadata sub-resource —
+ * there is no separate global-priority-list call this codebase already
+ * makes. Same v2/v3 envelope split as fetchIssueTypes' own top-level list
+ * call: v3 nests the field array under `fields`, v2 under `values` (a
+ * paginated-list envelope, maxResults/startAt/total/isLast). An earlier
+ * version of this function assumed the two were identical here — an
+ * artifact of an exploratory probe script that used a `??` fallback
+ * across both keys, which happened to mask the real difference. Caught
+ * live against advent (v2): a real Bug-type priority list came back
+ * empty under `fields`, present under `values`.
+ */
+export async function fetchProjectPriorities(projectKey, issueTypeId, opts = {}) {
+  const { env = process.env, fetcher = globalThis.fetch, lookup = defaultLookupFor(fetcher), apiVersion = 2, timeoutMs = 10_000, allowPrivateIp = false } = opts;
+  validateBaseUrl(env.JIRA_BASE_URL, allowPrivateIp);
+  const baseUrl = env.JIRA_BASE_URL.replace(/\/$/, '');
+  const headers = { ...buildAuthHeader(env), 'Content-Type': 'application/json' };
+
+  const url = `${baseUrl}/rest/api/${apiVersion}/issue/createmeta/${encodeURIComponent(projectKey)}/issuetypes/${encodeURIComponent(issueTypeId)}`;
+  const fetchOpts = { headers };
+  if (timeoutMs) fetchOpts.signal = AbortSignal.timeout(timeoutMs);
+  const response = await guardedFetch(url, fetchOpts, { fetcher, lookup, allowPrivateIp });
+
+  if (!response.ok) {
+    const err = new Error(`Jira API error ${response.status} fetching priorities for ${projectKey}`);
+    err.status = response.status;
+    throw err;
+  }
+
+  const raw = await response.json();
+  const fieldList = apiVersion >= 3 ? (raw.fields ?? []) : (raw.values ?? []);
+  const priorityField = fieldList.find(f => f.fieldId === 'priority');
+  return (priorityField?.allowedValues ?? []).map(p => ({ id: p.id, name: p.name }));
+}
+
 /**
  * Creates a new issue. `project`/`type` are passed straight through as
  * Jira's own {key}/{name} references — issue types are project-configurable,

package/skills/jtb/scripts/lib/mcp-server.mjs

@@ -522,7 +522,9 @@ async function callTicketAssign(args, { configDir, runTicketAssignFn }) {
     return { isError: true, content: [{ type: 'text', text: 'Missing required argument: to' }] };
   }
   const capture = capturingStream();
-  const { ok } = await runTicketAssignFn([args.ticket, `--to=${args.to}`], { configDir, stream: capture });
+  const cmdArgs = [args.ticket, `--to=${args.to}`];
+  if (args.confirm === true) cmdArgs.push('--confirm');
+  const { ok } = await runTicketAssignFn(cmdArgs, { configDir, stream: capture, cliHints: false });
   const content = [{ type: 'text', text: capture.text }];
   return ok ? { content } : { isError: true, content };
 }

package/skills/jtb/scripts/lib/mcp-tool-schemas.mjs

@@ -239,12 +239,13 @@ export const TOOLS = [
   },
   {
     name: 'ticket_assign',
-    description: 'Assign a ticket to yourself in its tracker (Jira/GitHub/Linear). Self-assign only — assigning to someone else is not supported yet. Requires a TicketLens Pro license.',
+    description: 'Assign a ticket in its tracker (Jira/GitHub/Linear). `to: "me"` self-assigns immediately, no confirm needed. Any other `to` (a name or email) assigns to another developer — Jira Cloud only for now; GitHub, Linear, and Jira Server/DC are refused. Resolves `to` against real assignable users before writing: called without `confirm: true`, it never assigns — it returns the matching candidate(s) (name + accountId) instead, so the exact person can be confirmed first. Called again with the same `to` and `confirm: true`, it executes only if `to` still resolves to exactly one candidate; 0 or 2+ matches always refuses, never guesses. Matches are cached locally per ticket\'s project for 3 days. Requires a TicketLens Pro license.',
     inputSchema: {
       type: 'object',
       properties: {
         ticket: { type: 'string', description: 'Ticket key, e.g. PROJ-123.' },
-        to: { type: 'string', description: 'Who to assign to — currently only "me" is accepted.' },
+        to: { type: 'string', description: '"me" to self-assign, or a name/email to search for and assign to another developer (Jira Cloud only).' },
+        confirm: { type: 'boolean', description: 'Must be true, alongside a `to` that resolves to exactly one match, to actually execute an assign-to-other. Not needed for `to: "me"`.' },
       },
       required: ['ticket', 'to'],
     },

package/skills/jtb/scripts/lib/ticket-command.mjs

@@ -14,10 +14,11 @@ import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { isLicensed, showUpgradePrompt } from './license.mjs';
 import { resolveConnection, findProfilesByPrefix } from './profile-resolver.mjs';
 import { resolveAdapter } from './resolve-adapter.mjs';
-import { checkCooldown, recordAction } from './ticket-action-cooldown.mjs';
+import { claimAction, releaseAction } from './ticket-action-cooldown.mjs';
 import { logAction } from './ticket-action-log.mjs';
-import { readMetadataCache, writeMetadataCache } from './ticket-metadata-cache.mjs';
+import { readMetadataCache, writeMetadataCache, isFresh, SINGLE_PROJECT_TTL_MS, mergeAssignableUsers, normalizeAssigneeQuery } from './ticket-metadata-cache.mjs';
 import { detectProjectOrTypeError, enrichCreateFailure } from './ticket-create-enrichment.mjs';
+import { enrichUpdateFailure } from './ticket-update-enrichment.mjs';
 import { TICKET_KEY_PATTERN, normalizeTicketKey } from './cli.mjs';
 import { scoreCandidates } from './duplicate-scorer.mjs';
 import { MAX_ATTACHMENTS } from './attachment-uploader.mjs';
@@ -32,6 +33,45 @@ function parseAttachPaths(cmdArgs) {
   return raw ? raw.split(',').map(p => p.trim()).filter(Boolean) : [];
 }
 
+/**
+ * Best-effort release of a claimAction cooldown claim (Backlog #34/ROADMAP
+ * 57) — releaseAction can itself throw (lock contention, same as any
+ * withLock caller in ticket-action-cooldown.mjs). A release is always
+ * called while already reporting some other outcome (a write failure, a
+ * refusal, an executed:false result); letting a lock-contention error
+ * replace that outcome would be strictly worse than just leaving the claim
+ * in place a few seconds longer — it expires on its own. Same "best
+ * effort — the claim expires by itself" reasoning already applied to
+ * ticket-worklog.mjs's own releaseClaim helper, DRY'd here across every
+ * write in this family instead of duplicated per function.
+ */
+export function safeRelease(releaseActionFn, ticketKey, action, configDir) {
+  try { releaseActionFn(ticketKey, action, { configDir }); } catch { /* best effort — the claim expires by itself */ }
+}
+
+/**
+ * claimAction can itself throw — lock contention on the same 2s deadline
+ * as any other withLock caller in ticket-action-cooldown.mjs. Left
+ * unguarded, that throw would fall through to the outer CLI/MCP error
+ * handler and be misreported as a real failure (and could trip the
+ * opt-in error-reporting pipeline) for what is actually correct, benign
+ * contention — the write is still safely refused either way, but the
+ * graceful "Skipped" UX this whole family is built around would be lost.
+ * Same guard ticket-worklog.mjs's own claimOrSkip already has; returns a
+ * `lockError` string instead of a boolean flag so each call site can
+ * fold it into its existing skip-message wording without a second
+ * lookup. Caught in code review before shipping — not exercised by the
+ * original 4-way live concurrency trial, which stayed under the 2s
+ * deadline.
+ */
+export function safeClaim(claimActionFn, ticketKey, action, configDir) {
+  try {
+    return claimActionFn(ticketKey, action, { configDir });
+  } catch (err) {
+    return { claimed: false, remainingMs: 0, lockError: err.message };
+  }
+}
+
 /**
  * GitHub has no PAT-compatible public API for uploading issue/comment
  * assets (confirmed via research — the only upload endpoint requires a
@@ -263,8 +303,8 @@ export async function runTicketComment(cmdArgs, {
   isLicensedFn = isLicensed,
   resolveConnectionFn = resolveConnection,
   resolveAdapterFn = resolveAdapter,
-  checkCooldownFn = checkCooldown,
-  recordActionFn = recordAction,
+  claimActionFn = claimAction,
+  releaseActionFn = releaseAction,
   logActionFn = logAction,
   actor = os.userInfo().username,
 } = {}) {
@@ -281,32 +321,36 @@ export async function runTicketComment(cmdArgs, {
   }
   const attachPaths = parseAttachPaths(cmdArgs);
 
-  const cooldown = checkCooldownFn(ticketKey, 'comment', { configDir });
-  if (cooldown.active) {
-    stream.write(`  Skipped — a comment was already posted to ${ticketKey} ${Math.ceil(cooldown.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
+  const claim = safeClaim(claimActionFn, ticketKey, 'comment', configDir);
+  if (!claim.claimed) {
+    stream.write(claim.lockError
+      ? `  ${ticketKey} not commented — could not take the cooldown lock (${claim.lockError}). Nothing was sent; safe to retry.\n`
+      : `  Skipped — a comment was already posted to ${ticketKey} ${Math.ceil(claim.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
     return { ok: false };
   }
 
   const resolved = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
-  if (!resolved) return { ok: false };
+  if (!resolved) { safeRelease(releaseActionFn, ticketKey, 'comment', configDir); return { ok: false }; }
   const { adapter } = resolved;
   const s = createStyler({ isTTY: stream.isTTY });
 
   // Uploaded BEFORE the comment write so a tracker capable of inline
   // rendering (Jira Server/DC via wiki markup, Jira Cloud via a real ADF
   // media node, Linear via Markdown) can fold it into the same atomic
-  // comment post rather than needing a second edit call.
+  // comment post rather than needing a second edit call. Inside the same
+  // try/catch as addComment — every adapter's attachFiles is documented to
+  // never throw (per-file errors are caught internally), but that is an
+  // implicit contract, not something to leave an un-released claim on if
+  // it were ever violated (caught in code review before shipping).
   let attachResult = null;
-  if (attachPaths.length && !refuseGithubAttachments(adapter, attachPaths, stream)) {
-    attachResult = await adapter.attachFiles(ticketKey, attachPaths);
-  }
-  const inlineSnippets = (attachResult?.uploaded ?? []).filter(a => a.inlineMarkup).map(a => a.inlineMarkup).join('\n\n');
-  const finalBody = inlineSnippets ? `${body}\n\n${inlineSnippets}` : body;
-  const extraAdfNodes = (attachResult?.uploaded ?? []).filter(a => a.adfMediaNode).map(a => a.adfMediaNode);
-
   try {
+    if (attachPaths.length && !refuseGithubAttachments(adapter, attachPaths, stream)) {
+      attachResult = await adapter.attachFiles(ticketKey, attachPaths);
+    }
+    const inlineSnippets = (attachResult?.uploaded ?? []).filter(a => a.inlineMarkup).map(a => a.inlineMarkup).join('\n\n');
+    const finalBody = inlineSnippets ? `${body}\n\n${inlineSnippets}` : body;
+    const extraAdfNodes = (attachResult?.uploaded ?? []).filter(a => a.adfMediaNode).map(a => a.adfMediaNode);
     const result = await adapter.addComment(ticketKey, finalBody, extraAdfNodes.length ? { extraAdfNodes } : {});
-    recordActionFn(ticketKey, 'comment', { configDir });
     // attachPaths (every path attempted, raw) plus attachedFilenames (what
     // actually landed) — a partial attach failure is reconstructable from
     // the difference between the two, not just silently absent from audit.
@@ -314,6 +358,7 @@ export async function runTicketComment(cmdArgs, {
     stream.write(`  ${s.green('✔')} Comment posted to ${s.brand(s.bold(ticketKey))}${result.url ? ` (${result.url})` : ''}\n` + formatAttachSummary(attachResult, s));
     return { ok: true };
   } catch (err) {
+    safeRelease(releaseActionFn, ticketKey, 'comment', configDir);
     // Attachments (if any) genuinely landed on the tracker before this
     // write was attempted — formatAttachSummary is still shown here so a
     // caller retrying the whole command doesn't blindly re-upload them.
@@ -383,8 +428,8 @@ export async function runTicketTransition(cmdArgs, {
   isLicensedFn = isLicensed,
   resolveConnectionFn = resolveConnection,
   resolveAdapterFn = resolveAdapter,
-  checkCooldownFn = checkCooldown,
-  recordActionFn = recordAction,
+  claimActionFn = claimAction,
+  releaseActionFn = releaseAction,
   logActionFn = logAction,
   actor = os.userInfo().username,
   cliHints = true,
@@ -407,42 +452,101 @@ export async function runTicketTransition(cmdArgs, {
     return { ok: false };
   }
 
-  const cooldown = checkCooldownFn(ticketKey, 'transition', { configDir });
-  if (cooldown.active) {
-    stream.write(`  Skipped — ${ticketKey} was already transitioned ${Math.ceil(cooldown.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
+  const claim = safeClaim(claimActionFn, ticketKey, 'transition', configDir);
+  if (!claim.claimed) {
+    stream.write(claim.lockError
+      ? `  ${ticketKey} not transitioned — could not take the cooldown lock (${claim.lockError}). Nothing was sent; safe to retry.\n`
+      : `  Skipped — ${ticketKey} was already transitioned ${Math.ceil(claim.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
     return { ok: false };
   }
 
   const resolved = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
-  if (!resolved) return { ok: false };
+  if (!resolved) { safeRelease(releaseActionFn, ticketKey, 'transition', configDir); return { ok: false }; }
   const { adapter } = resolved;
 
   try {
     const result = await adapter.transition(ticketKey, target);
     if (!result.executed) {
+      safeRelease(releaseActionFn, ticketKey, 'transition', configDir);
       const optionsHint = result.options?.length ? ` Valid options: ${result.options.map(o => o.name).join(', ')}.` : '';
       stream.write(`  Not transitioned — ${result.reason}.${optionsHint}\n`);
       return { ok: false, reason: result.reason };
     }
-    recordActionFn(ticketKey, 'transition', { configDir });
     logActionFn({ ticketKey, action: 'transition', actor, tracker: adapter.type, detail: { to: result.to } }, { configDir });
     const s = createStyler({ isTTY: stream.isTTY });
     stream.write(`  ${s.green('✔')} ${s.brand(s.bold(ticketKey))} transitioned to ${s.bold(`"${result.to}"`)}.\n`);
     return { ok: true };
   } catch (err) {
+    safeRelease(releaseActionFn, ticketKey, 'transition', configDir);
     stream.write(formatWriteFailure(ticketKey, err));
     return { ok: false };
   }
 }
 
 /**
- * Self-assign only — `--to` currently only accepts the literal "me".
- * Arbitrary-user assignment needs a per-tracker user-search step this
- * codebase doesn't have yet; kept as an explicit, rejected value now so
- * a future `--to=someone@else.com` doesn't silently redefine what a
- * bare/missing --to means today.
+ * Derives the project-key portion of a ticket key — used only to key the
+ * local assignable-users cache, never for validation. Jira's own API stays
+ * the source of truth for whether the ticket key is real; a ticket key
+ * this can't parse just means caching is skipped, not a hard failure.
+ */
+function projectKeyFromTicket(ticketKey) {
+  const hyphenIndex = ticketKey.lastIndexOf('-');
+  return hyphenIndex > 0 ? ticketKey.slice(0, hyphenIndex) : null;
+}
+
+/**
+ * Resolves a free-text `--to` query into assignable-user candidates,
+ * checking the local cache (3-day TTL, per project+query — ROADMAP 61)
+ * before calling the adapter. Read-only: never assigns, never touches
+ * cooldown. Exported for direct unit testing, same convention as
+ * `resolveTicketAdapter`.
+ */
+export async function resolveAssigneeCandidates(adapter, ticketKey, query, {
+  profileName,
+  configDir = DEFAULT_CONFIG_DIR,
+  readMetadataCacheFn = readMetadataCache,
+  writeMetadataCacheFn = writeMetadataCache,
+} = {}) {
+  const projectKey = projectKeyFromTicket(ticketKey);
+  const cached = readMetadataCacheFn(profileName, configDir);
+
+  if (projectKey) {
+    const normalizedQuery = normalizeAssigneeQuery(query);
+    const cachedCandidates = cached?.assignableUsersByProject?.[projectKey]?.[normalizedQuery];
+    const cachedAt = cached?.assignableUsersFetchedAt?.[projectKey]?.[normalizedQuery];
+    if (cachedCandidates && isFresh(cachedAt, SINGLE_PROJECT_TTL_MS)) {
+      return cachedCandidates;
+    }
+  }
+
+  const candidates = await adapter.searchAssignableUsers(ticketKey, query);
+
+  if (projectKey) {
+    const { assignableUsersByProject, assignableUsersFetchedAt } = mergeAssignableUsers(cached, projectKey, query, candidates);
+    writeMetadataCacheFn(profileName, {
+      projects: cached?.projects ?? [],
+      issueTypesByProject: cached?.issueTypesByProject ?? {},
+      issueTypesFetchedAt: cached?.issueTypesFetchedAt ?? {},
+      projectsFetchedAt: cached?.projectsFetchedAt ?? null,
+      assignableUsersByProject,
+      assignableUsersFetchedAt,
+    }, configDir);
+  }
+
+  return candidates;
+}
+
+/**
+ * `--to=me` self-assigns immediately — unchanged fast path, no discovery,
+ * no confirm. Any other `--to` resolves a real person first (ROADMAP 61):
+ * Jira Cloud only (Server/DC's assignable-user search is unverified —
+ * refuses cleanly rather than guessing), and only executes when exactly
+ * one candidate matches AND --confirm is given, mirroring `transition`'s
+ * list-then-confirm shape — notifying a colleague deserves the same
+ * reviewed-before-write gate as a workflow-state change.
  *
- * @param {string[]} cmdArgs - [ticketKey, '--to=me']
+ * @param {string[]} cmdArgs - [ticketKey, '--to=me'] or [ticketKey, '--to=...', '--confirm']
+ * @param {boolean} [cliHints] - see runTicketTransitionList's cliHints doc
  * @returns {Promise<{ ok: boolean }>}
  */
 export async function runTicketAssign(cmdArgs, {
@@ -451,41 +555,112 @@ export async function runTicketAssign(cmdArgs, {
   isLicensedFn = isLicensed,
   resolveConnectionFn = resolveConnection,
   resolveAdapterFn = resolveAdapter,
-  checkCooldownFn = checkCooldown,
-  recordActionFn = recordAction,
+  claimActionFn = claimAction,
+  releaseActionFn = releaseAction,
   logActionFn = logAction,
+  readMetadataCacheFn = readMetadataCache,
+  writeMetadataCacheFn = writeMetadataCache,
   actor = os.userInfo().username,
+  cliHints = true,
 } = {}) {
-  const usage = 'Usage: ticketlens assign TICKET-KEY --to=me\n';
+  const usage = cliHints
+    ? 'Usage: ticketlens assign TICKET-KEY --to=me | --to="name or email" --confirm\n'
+    : 'Usage: assign requires ticket and to; a to other than "me" also needs confirm: true to execute.\n';
   if (!requireLicense(isLicensedFn, configDir, 'ticketlens assign', stream)) return { ok: false };
 
   const ticketKey = requireTicketKey(cmdArgs, usage, stream);
   if (!ticketKey) return { ok: false };
 
   const to = parseFlag(cmdArgs, 'to');
-  if (to !== 'me') {
-    stream.write(to ? `  --to="${to}" is not yet supported — only --to=me (self-assign) is available.\n` : usage);
+  if (!to) {
+    stream.write(usage);
     return { ok: false };
   }
 
-  const cooldown = checkCooldownFn(ticketKey, 'assign', { configDir });
-  if (cooldown.active) {
-    stream.write(`  Skipped — ${ticketKey} was already assigned ${Math.ceil(cooldown.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
-    return { ok: false };
+  if (to === 'me') {
+    const claim = safeClaim(claimActionFn, ticketKey, 'assign', configDir);
+    if (!claim.claimed) {
+      stream.write(claim.lockError
+        ? `  ${ticketKey} not assigned — could not take the cooldown lock (${claim.lockError}). Nothing was sent; safe to retry.\n`
+        : `  Skipped — ${ticketKey} was already assigned ${Math.ceil(claim.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
+      return { ok: false };
+    }
+
+    const resolved = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+    if (!resolved) { safeRelease(releaseActionFn, ticketKey, 'assign', configDir); return { ok: false }; }
+    const { adapter } = resolved;
+
+    try {
+      const result = await adapter.assignToSelf(ticketKey);
+      logActionFn({ ticketKey, action: 'assign', actor, tracker: adapter.type, detail: { assignee: result.assignee } }, { configDir });
+      const s = createStyler({ isTTY: stream.isTTY });
+      stream.write(`  ${s.green('✔')} ${s.brand(s.bold(ticketKey))} assigned to ${s.bold(result.assignee)}.\n`);
+      return { ok: true };
+    } catch (err) {
+      safeRelease(releaseActionFn, ticketKey, 'assign', configDir);
+      stream.write(formatWriteFailure(ticketKey, err));
+      return { ok: false };
+    }
   }
 
   const resolved = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
   if (!resolved) return { ok: false };
-  const { adapter } = resolved;
+  const { adapter, conn } = resolved;
+
+  if (adapter.type !== 'jira') {
+    stream.write(`  Assigning to another developer is Jira-only right now — ${adapter.type} is not supported.\n`);
+    return { ok: false };
+  }
+  if (conn.auth !== 'cloud') {
+    stream.write('  Assigning to another developer needs Jira Cloud — Server/DC is not supported yet.\n');
+    return { ok: false };
+  }
 
+  const s = createStyler({ isTTY: stream.isTTY });
+  let candidates;
   try {
-    const result = await adapter.assignToSelf(ticketKey);
-    recordActionFn(ticketKey, 'assign', { configDir });
-    logActionFn({ ticketKey, action: 'assign', actor, tracker: adapter.type, detail: { assignee: result.assignee } }, { configDir });
-    const s = createStyler({ isTTY: stream.isTTY });
-    stream.write(`  ${s.green('✔')} ${s.brand(s.bold(ticketKey))} assigned to ${s.bold(result.assignee)}.\n`);
+    candidates = await resolveAssigneeCandidates(adapter, ticketKey, to, { profileName: conn.profileName, configDir, readMetadataCacheFn, writeMetadataCacheFn });
+  } catch (err) {
+    stream.write(formatWriteFailure(ticketKey, err));
+    return { ok: false };
+  }
+
+  if (candidates.length === 0) {
+    stream.write(`  No assignable user found matching "${to}" for ${s.brand(s.bold(ticketKey))}.\n`);
+    return { ok: false };
+  }
+
+  if (candidates.length > 1) {
+    stream.write(`  ${candidates.length} users match "${to}" — narrow the query:\n\n`);
+    for (const c of candidates) stream.write(`    ${s.brand('●')} ${c.displayName}  ${s.dim(c.accountId)}\n`);
+    return { ok: false };
+  }
+
+  const [candidate] = candidates;
+
+  if (!cmdArgs.includes('--confirm')) {
+    stream.write(`  Match: ${s.bold(candidate.displayName)}  ${s.dim(candidate.accountId)}\n`);
+    stream.write(cliHints
+      ? `\n  Run again with --to="${to}" --confirm to execute.\n`
+      : `\n  Call again with to="${to}" and confirm: true to execute.\n`);
+    return { ok: false };
+  }
+
+  const claim = safeClaim(claimActionFn, ticketKey, 'assign', configDir);
+  if (!claim.claimed) {
+    stream.write(claim.lockError
+      ? `  ${ticketKey} not assigned — could not take the cooldown lock (${claim.lockError}). Nothing was sent; safe to retry.\n`
+      : `  Skipped — ${ticketKey} was already assigned ${Math.ceil(claim.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
+    return { ok: false };
+  }
+
+  try {
+    await adapter.assignToUser(ticketKey, candidate.accountId);
+    logActionFn({ ticketKey, action: 'assign', actor, tracker: adapter.type, detail: { assignee: candidate.displayName, accountId: candidate.accountId } }, { configDir });
+    stream.write(`  ${s.green('✔')} ${s.brand(s.bold(ticketKey))} assigned to ${s.bold(candidate.displayName)}.\n`);
     return { ok: true };
   } catch (err) {
+    safeRelease(releaseActionFn, ticketKey, 'assign', configDir);
     stream.write(formatWriteFailure(ticketKey, err));
     return { ok: false };
   }
@@ -653,8 +828,8 @@ export async function runTicketLink(cmdArgs, {
   isLicensedFn = isLicensed,
   resolveConnectionFn = resolveConnection,
   resolveAdapterFn = resolveAdapter,
-  checkCooldownFn = checkCooldown,
-  recordActionFn = recordAction,
+  claimActionFn = claimAction,
+  releaseActionFn = releaseAction,
   logActionFn = logAction,
   actor = os.userInfo().username,
   cliHints = true,
@@ -680,17 +855,20 @@ export async function runTicketLink(cmdArgs, {
   }
 
   const cooldownKey = `${sourceKey}:${targetKey}`;
-  const cooldown = checkCooldownFn(cooldownKey, 'link', { configDir });
-  if (cooldown.active) {
-    stream.write(`  Skipped — ${sourceKey} was already linked to ${targetKey} ${Math.ceil(cooldown.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
+  const claim = safeClaim(claimActionFn, cooldownKey, 'link', configDir);
+  if (!claim.claimed) {
+    stream.write(claim.lockError
+      ? `  ${sourceKey} not linked — could not take the cooldown lock (${claim.lockError}). Nothing was sent; safe to retry.\n`
+      : `  Skipped — ${sourceKey} was already linked to ${targetKey} ${Math.ceil(claim.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
     return { ok: false };
   }
 
   const resolved = resolveTicketAdapter(sourceKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
-  if (!resolved) return { ok: false };
+  if (!resolved) { safeRelease(releaseActionFn, cooldownKey, 'link', configDir); return { ok: false }; }
   const { adapter } = resolved;
 
   if (adapter.type === 'github' && type.toLowerCase() !== 'duplicate') {
+    safeRelease(releaseActionFn, cooldownKey, 'link', configDir);
     stream.write(`  GitHub only supports linking as a duplicate — no generic link types. Got type "${type}".\n`);
     return { ok: false };
   }
@@ -701,11 +879,11 @@ export async function runTicketLink(cmdArgs, {
   try {
     const result = await adapter.linkTo(sourceKey, targetKey, type);
     if (!result.executed) {
+      safeRelease(releaseActionFn, cooldownKey, 'link', configDir);
       const optionsHint = result.options?.length ? ` Valid options: ${result.options.join(', ')}.` : '';
       stream.write(`  Not linked — ${result.reason}.${optionsHint}\n`);
       return { ok: false, reason: result.reason };
     }
-    recordActionFn(cooldownKey, 'link', { configDir });
     logActionFn({ ticketKey: sourceKey, action: 'link', actor, tracker: adapter.type, detail: { targetKey, type } }, { configDir });
     const s = createStyler({ isTTY: stream.isTTY });
     stream.write(
@@ -715,6 +893,7 @@ export async function runTicketLink(cmdArgs, {
     );
     return { ok: true };
   } catch (err) {
+    safeRelease(releaseActionFn, cooldownKey, 'link', configDir);
     stream.write(formatWriteFailure(sourceKey, err));
     return { ok: false };
   }
@@ -747,9 +926,11 @@ export async function runTicketUpdate(cmdArgs, {
   isLicensedFn = isLicensed,
   resolveConnectionFn = resolveConnection,
   resolveAdapterFn = resolveAdapter,
-  checkCooldownFn = checkCooldown,
-  recordActionFn = recordAction,
+  claimActionFn = claimAction,
+  releaseActionFn = releaseAction,
   logActionFn = logAction,
+  readMetadataCacheFn = readMetadataCache,
+  writeMetadataCacheFn = writeMetadataCache,
   actor = os.userInfo().username,
 } = {}) {
   const usage = 'Usage: ticketlens update TICKET-KEY [--title="..."] [--description="..."] [--add-labels=a,b] [--remove-labels=c] [--priority="High"]\n';
@@ -771,34 +952,45 @@ export async function runTicketUpdate(cmdArgs, {
     return { ok: false };
   }
 
-  const cooldown = checkCooldownFn(ticketKey, 'update', { configDir });
-  if (cooldown.active) {
-    stream.write(`  Skipped — ${ticketKey} was already updated ${Math.ceil(cooldown.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
+  const claim = safeClaim(claimActionFn, ticketKey, 'update', configDir);
+  if (!claim.claimed) {
+    stream.write(claim.lockError
+      ? `  ${ticketKey} not updated — could not take the cooldown lock (${claim.lockError}). Nothing was sent; safe to retry.\n`
+      : `  Skipped — ${ticketKey} was already updated ${Math.ceil(claim.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
     return { ok: false };
   }
 
   const resolved = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
-  if (!resolved) return { ok: false };
-  const { adapter } = resolved;
+  if (!resolved) { safeRelease(releaseActionFn, ticketKey, 'update', configDir); return { ok: false }; }
+  const { adapter, conn } = resolved;
 
   if (adapter.type === 'github' && priority !== undefined) {
+    safeRelease(releaseActionFn, ticketKey, 'update', configDir);
     stream.write(`  GitHub Issues have no native priority field — cannot update priority on ${ticketKey}. Remove --priority and retry.\n`);
     return { ok: false };
   }
 
   try {
-    const result = await adapter.updateFields(ticketKey, { title, description, priority, addLabels, removeLabels });
+    const result = await adapter.updateFields(ticketKey, { title, description, priority, addLabels, removeLabels }, { readMetadataCacheFn, writeMetadataCacheFn, profileName: conn.profileName, configDir });
     const hasApplied = Object.keys(result.applied).length > 0;
     const hasErrors = Object.keys(result.errors).length > 0;
 
     if (hasApplied) {
-      recordActionFn(ticketKey, 'update', { configDir });
       logActionFn({ ticketKey, action: 'update', actor, tracker: adapter.type, detail: { ...result.applied, failed: Object.keys(result.errors) } }, { configDir });
+    } else {
+      // Nothing landed — release so a caller fixing the failed field(s) can
+      // retry immediately, same "release on definite failure" rule as every
+      // other write in this family. A partial success (hasApplied &&
+      // hasErrors) deliberately keeps the claim armed, unchanged from the
+      // old recordActionFn-only-when-hasApplied behavior.
+      safeRelease(releaseActionFn, ticketKey, 'update', configDir);
     }
     stream.write(formatUpdateResult(ticketKey, result, createStyler({ isTTY: stream.isTTY })));
     return hasErrors ? { ok: false, applied: result.applied, errors: result.errors } : { ok: true, applied: result.applied };
   } catch (err) {
-    stream.write(formatWriteFailure(ticketKey, err));
+    safeRelease(releaseActionFn, ticketKey, 'update', configDir);
+    const enrichment = await enrichUpdateFailure(err, { adapter, projectKey: projectKeyFromTicket(ticketKey), profileName: conn.profileName, configDir, readMetadataCacheFn, writeMetadataCacheFn });
+    stream.write(formatWriteFailure(ticketKey, err) + enrichment);
     return { ok: false };
   }
 }
@@ -833,8 +1025,8 @@ export async function runTicketCreate(cmdArgs, {
   isLicensedFn = isLicensed,
   resolveConnectionFn = resolveConnection,
   resolveAdapterFn = resolveAdapter,
-  checkCooldownFn = checkCooldown,
-  recordActionFn = recordAction,
+  claimActionFn = claimAction,
+  releaseActionFn = releaseAction,
   logActionFn = logAction,
   readMetadataCacheFn = readMetadataCache,
   writeMetadataCacheFn = writeMetadataCache,
@@ -899,9 +1091,11 @@ export async function runTicketCreate(cmdArgs, {
   // text that can themselves contain ":", which would let two genuinely
   // different tuples collide onto the same cooldown key.
   const cooldownKey = `create:${JSON.stringify([project ?? '', type ?? '', summary])}`;
-  const cooldown = checkCooldownFn(cooldownKey, 'create', { configDir });
-  if (cooldown.active) {
-    stream.write(`  Skipped — a ticket with this summary was already created ${Math.ceil(cooldown.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
+  const claim = safeClaim(claimActionFn, cooldownKey, 'create', configDir);
+  if (!claim.claimed) {
+    stream.write(claim.lockError
+      ? `  Nothing was created — could not take the cooldown lock (${claim.lockError}). Safe to retry.\n`
+      : `  Skipped — a ticket with this summary was already created ${Math.ceil(claim.remainingMs / 1000)}s ago. Wait a moment before retrying.\n`);
     return { ok: false };
   }
 
@@ -909,6 +1103,9 @@ export async function runTicketCreate(cmdArgs, {
   try {
     result = await adapter.createTicket({ project, type, summary, description });
   } catch (err) {
+    // Definite failure — no ticket was created, so the claim is released to
+    // let a corrected retry through immediately (Backlog #34/ROADMAP 57).
+    safeRelease(releaseActionFn, cooldownKey, 'create', configDir);
     // profileName is only resolved when this failure is actually
     // project/issuetype-shaped — not on every failure, and never on the
     // success path — since it exists solely to scope the enrichment cache.
@@ -922,12 +1119,13 @@ export async function runTicketCreate(cmdArgs, {
   }
 
   // The write already landed — a real, external, hard-to-walk-back ticket
-  // now exists. From here on, nothing may report this as a failed write:
-  // cooldown/audit bookkeeping is best-effort, never the reason a real
-  // success gets mistaken for one (which risks a caller retrying and
-  // fabricating a genuine duplicate).
+  // now exists. From here on, nothing may report this as a failed write.
+  // The cooldown claim was already recorded atomically at claim time above
+  // (no separate recordActionFn call needed here); only the audit log is
+  // best-effort — a logging failure must never make a real success look
+  // like a failure (which risks a caller retrying and fabricating a
+  // genuine duplicate).
   try {
-    recordActionFn(cooldownKey, 'create', { configDir });
     logActionFn({ ticketKey: result.key, action: 'create', actor, tracker: adapter.type, detail: { project, type } }, { configDir });
   } catch (bookkeepingErr) {
     stream.write(`  Warning: ${result.key} was created but could not be logged: ${bookkeepingErr.message}\n`);

package/skills/jtb/scripts/lib/ticket-metadata-cache.mjs

@@ -21,7 +21,35 @@
  *   projects: [{key, name}],
  *   issueTypesByProject:  {KEY: [{id, name}]},
  *   issueTypesFetchedAt:  {KEY: iso timestamp}  // per-project, either access pattern
+ *   assignableUsersByProject:  {KEY: {normalizedQuery: [{accountId, displayName}]}},
+ *   assignableUsersFetchedAt:  {KEY: {normalizedQuery: iso timestamp}},
+ *   prioritiesByProject:  {KEY: [{id, name}]},
+ *   prioritiesFetchedAt:  {KEY: iso timestamp},
+ *   labelsByTeam:  {TEAM_ID: [{id, name}]},
+ *   labelsFetchedAt:  {TEAM_ID: iso timestamp}
  * }
+ *
+ * assignableUsersByProject/assignableUsersFetchedAt (ROADMAP 61) share this
+ * file rather than a new one — same profile-scoped Jira-lookup cache, same
+ * 3-day freshness bar as a single-project issue-types lookup. Nested one
+ * level deeper than issueTypesByProject because Jira's own
+ * `user/assignable/search` has no "list everyone" mode (query is required
+ * unless accountId is given) — there is no per-project roster to cache,
+ * only per-(project, query) result pages, each with its own clock.
+ *
+ * prioritiesByProject/prioritiesFetchedAt (Backlog #34/ROADMAP 57 follow-up)
+ * are per-project like issueTypesByProject, not global — confirmed live
+ * against both a Cloud instance (corenexus) and a Server/DC instance
+ * (advent) that priority schemes are project-scoped, not instance-wide.
+ * Reactive-enrichment-only, same 3-day SINGLE_PROJECT_TTL_MS bar, same
+ * design as issue-types: never blocks a write, only enriches the error
+ * message after Jira's own 400.
+ *
+ * labelsByTeam/labelsFetchedAt is Linear-only — Linear requires labels to
+ * pre-exist as real objects (unlike Jira's freeform labels), and its own
+ * `updateFields` re-fetches the full team label list via GraphQL on every
+ * single call with no caching. Keyed by team id (Linear's label scope),
+ * same 3-day freshness bar.
  */
 
 import fs from 'node:fs';
@@ -62,6 +90,67 @@ export function mergeProjectIssueTypes(cached, projectKey, types, fetchedAt = ne
   return { issueTypesByProject, issueTypesFetchedAt };
 }
 
+/**
+ * Trim + lowercase — the one normalization every assignable-users cache
+ * read and write must agree on, so "Jane", " jane ", and "JANE" share one
+ * cache entry instead of three.
+ */
+export function normalizeAssigneeQuery(query) {
+  return String(query).trim().toLowerCase();
+}
+
+/**
+ * Merges one (project, query) assignable-users search result into an
+ * existing (possibly null) cached map — same shape and same
+ * Object.create(null) defense as mergeProjectIssueTypes, one level deeper
+ * since a project can have many independently-fresh cached queries. Both
+ * projectKey and the normalized query are unvalidated values reaching a
+ * key position.
+ */
+export function mergeAssignableUsers(cached, projectKey, query, candidates, fetchedAt = new Date().toISOString()) {
+  const normalizedQuery = normalizeAssigneeQuery(query);
+
+  const assignableUsersByProject = Object.assign(Object.create(null), cached?.assignableUsersByProject ?? {});
+  const projectQueries = Object.assign(Object.create(null), assignableUsersByProject[projectKey] ?? {});
+  projectQueries[normalizedQuery] = candidates;
+  assignableUsersByProject[projectKey] = projectQueries;
+
+  const assignableUsersFetchedAt = Object.assign(Object.create(null), cached?.assignableUsersFetchedAt ?? {});
+  const projectQueryTimestamps = Object.assign(Object.create(null), assignableUsersFetchedAt[projectKey] ?? {});
+  projectQueryTimestamps[normalizedQuery] = fetchedAt;
+  assignableUsersFetchedAt[projectKey] = projectQueryTimestamps;
+
+  return { assignableUsersByProject, assignableUsersFetchedAt };
+}
+
+/**
+ * Merges one project's priority list into an existing (possibly null)
+ * cached map — same shape and Object.create(null) defense as
+ * mergeProjectIssueTypes, for the same reason (projectKey is an
+ * unvalidated CLI/tracker value reaching a key position).
+ */
+export function mergeProjectPriorities(cached, projectKey, priorities, fetchedAt = new Date().toISOString()) {
+  const prioritiesByProject = Object.assign(Object.create(null), cached?.prioritiesByProject ?? {});
+  prioritiesByProject[projectKey] = priorities;
+  const prioritiesFetchedAt = Object.assign(Object.create(null), cached?.prioritiesFetchedAt ?? {});
+  prioritiesFetchedAt[projectKey] = fetchedAt;
+  return { prioritiesByProject, prioritiesFetchedAt };
+}
+
+/**
+ * Merges one team's label list into an existing (possibly null) cached
+ * map — same shape and Object.create(null) defense as
+ * mergeProjectIssueTypes; teamId is Linear's own UUID, not user-supplied,
+ * but the same defensive pattern is kept for consistency with its siblings.
+ */
+export function mergeTeamLabels(cached, teamId, labels, fetchedAt = new Date().toISOString()) {
+  const labelsByTeam = Object.assign(Object.create(null), cached?.labelsByTeam ?? {});
+  labelsByTeam[teamId] = labels;
+  const labelsFetchedAt = Object.assign(Object.create(null), cached?.labelsFetchedAt ?? {});
+  labelsFetchedAt[teamId] = fetchedAt;
+  return { labelsByTeam, labelsFetchedAt };
+}
+
 /**
  * Returns the absolute path to the ticket-metadata cache file for a profile.
  */
@@ -84,7 +173,7 @@ export function metadataCachePath(profileName, configDir = DEFAULT_CONFIG_DIR) {
  * @param {string|null} profileName
  * @param {string} [configDir]
  * @param {number} [ttlMs] - override TTL in ms for this file's own GC deletion; defaults to METADATA_TTL_MS (7d)
- * @returns {{ projects: {key:string,name:string}[], issueTypesByProject: object, issueTypesFetchedAt: object, projectsFetchedAt: string|null, fetchedAt: string } | null}
+ * @returns {{ projects: {key:string,name:string}[], issueTypesByProject: object, issueTypesFetchedAt: object, assignableUsersByProject: object, assignableUsersFetchedAt: object, prioritiesByProject: object, prioritiesFetchedAt: object, labelsByTeam: object, labelsFetchedAt: object, projectsFetchedAt: string|null, fetchedAt: string } | null}
  */
 export function readMetadataCache(profileName, configDir = DEFAULT_CONFIG_DIR, ttlMs = METADATA_TTL_MS) {
   const filePath = metadataCachePath(profileName, configDir);
@@ -107,6 +196,12 @@ export function readMetadataCache(profileName, configDir = DEFAULT_CONFIG_DIR, t
     projects: data.projects ?? [],
     issueTypesByProject: data.issueTypesByProject ?? {},
     issueTypesFetchedAt: data.issueTypesFetchedAt ?? {},
+    assignableUsersByProject: data.assignableUsersByProject ?? {},
+    assignableUsersFetchedAt: data.assignableUsersFetchedAt ?? {},
+    prioritiesByProject: data.prioritiesByProject ?? {},
+    prioritiesFetchedAt: data.prioritiesFetchedAt ?? {},
+    labelsByTeam: data.labelsByTeam ?? {},
+    labelsFetchedAt: data.labelsFetchedAt ?? {},
     projectsFetchedAt: data.projectsFetchedAt ?? null,
     fetchedAt: data.fetchedAt,
   };
@@ -119,7 +214,7 @@ export function readMetadataCache(profileName, configDir = DEFAULT_CONFIG_DIR, t
  * updates (e.g. a single-project fetch merging into an existing
  * multi-project cache) — this function persists exactly what it's given.
  */
-export function writeMetadataCache(profileName, { projects = [], issueTypesByProject = {}, issueTypesFetchedAt = {}, projectsFetchedAt = null } = {}, configDir = DEFAULT_CONFIG_DIR) {
+export function writeMetadataCache(profileName, { projects = [], issueTypesByProject = {}, issueTypesFetchedAt = {}, assignableUsersByProject = {}, assignableUsersFetchedAt = {}, prioritiesByProject = {}, prioritiesFetchedAt = {}, labelsByTeam = {}, labelsFetchedAt = {}, projectsFetchedAt = null } = {}, configDir = DEFAULT_CONFIG_DIR) {
   const filePath = metadataCachePath(profileName, configDir);
   try {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -129,6 +224,12 @@ export function writeMetadataCache(profileName, { projects = [], issueTypesByPro
       projects,
       issueTypesByProject,
       issueTypesFetchedAt,
+      assignableUsersByProject,
+      assignableUsersFetchedAt,
+      prioritiesByProject,
+      prioritiesFetchedAt,
+      labelsByTeam,
+      labelsFetchedAt,
     }));
   } catch {
     // Non-fatal

package/skills/jtb/scripts/lib/ticket-update-enrichment.mjs

@@ -0,0 +1,66 @@
+/**
+ * Failure-message enrichment for `ticket_update`'s priority field —
+ * reactive only, never runs on the success path. Same structure as
+ * ticket-create-enrichment.mjs's project/issuetype enrichment; kept as a
+ * separate file (not merged into that one) since the two enrich different
+ * fields for a different write and share no state beyond the cache module.
+ */
+
+import { SINGLE_PROJECT_TTL_MS, isFresh, mergeProjectPriorities } from './ticket-metadata-cache.mjs';
+
+/**
+ * Detects whether an update failure is shaped like a bad priority name —
+ * the only case this enrichment applies to. Jira surfaces this via its
+ * own real `err.details.errors.priority` key, confirmed by direct
+ * observation against a live Cloud instance (corenexus) and a live
+ * Server/DC instance (advent) on 2026-09-24. Anything else (rate limits,
+ * network errors, generic 4xx/5xx, a title/description/label failure)
+ * returns false — enrichment never applies there.
+ */
+export function detectPriorityError(err) {
+  return Boolean(err?.details?.errors && 'priority' in err.details.errors);
+}
+
+/**
+ * Best-effort failure-message enrichment for ticket_update's priority
+ * field — reactive only, never runs on the success path or for a
+ * non-priority failure. Reuses a cached per-project priority listing when
+ * fresh (no extra network call); refreshes it when missing/stale. A
+ * refresh failure is swallowed entirely and nothing is written to the
+ * cache: this can only ever make an error message MORE informative, never
+ * introduce a new way for ticketlens update to fail or a new way to
+ * poison the cache. Jira-only — GitHub has no priority field (refused
+ * upstream in ticket-command.mjs) and Linear already returns a structured,
+ * local `{reason:'not-found', options}` error with no network round trip.
+ *
+ * Freshness is keyed on the timestamp existing, not on the cached array
+ * having entries — a project with no priority-capable issue type at all
+ * genuinely caches `[]`, and `[].length` is falsy, so gating on length
+ * would re-walk every issue type (adapter.listPriorities' own sequential
+ * per-type loop) on every single subsequent failed update, forever,
+ * never respecting SINGLE_PROJECT_TTL_MS. Caught in code review before
+ * shipping — the sibling ticket-create-enrichment.mjs has this same
+ * length-gated pattern for issueTypesByProject, not fixed here since its
+ * refresh is a single call, not a sequential loop.
+ */
+export async function enrichUpdateFailure(err, { adapter, projectKey, profileName, configDir, readMetadataCacheFn, writeMetadataCacheFn }) {
+  if (!detectPriorityError(err) || adapter.type !== 'jira' || !projectKey) return '';
+
+  let cached = readMetadataCacheFn(profileName, configDir);
+  const hasFreshPriorities = cached?.prioritiesByProject?.[projectKey] !== undefined
+    && isFresh(cached?.prioritiesFetchedAt?.[projectKey], SINGLE_PROJECT_TTL_MS);
+
+  if (!hasFreshPriorities) {
+    try {
+      const { prioritiesByProject, prioritiesFetchedAt } = mergeProjectPriorities(cached, projectKey, await adapter.listPriorities(projectKey));
+      cached = { ...cached, prioritiesByProject, prioritiesFetchedAt };
+      writeMetadataCacheFn(profileName, cached, configDir);
+    } catch {
+      return '';
+    }
+  }
+
+  const priorities = cached?.prioritiesByProject?.[projectKey];
+  if (!priorities?.length) return '';
+  return `  Known priorities for ${projectKey}: ${priorities.map(p => p.name).join(', ')}.\n`;
+}