ticketlens 0.41.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.41.0",
+  "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/scripts/lib/adapters/jira-adapter.mjs

@@ -1,4 +1,4 @@
-import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses, fetchProjects, fetchIssueTypes, postComment, getTransitions, postTransition, assignIssue, fetchAssignableUsers, 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';
@@ -211,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/jira-client.mjs

@@ -738,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/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, 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,29 +452,32 @@ 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 };
   }
@@ -507,8 +555,8 @@ 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,
@@ -530,24 +578,26 @@ export async function runTicketAssign(cmdArgs, {
   }
 
   if (to === 'me') {
-    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`);
+    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) return { ok: false };
+    if (!resolved) { safeRelease(releaseActionFn, ticketKey, 'assign', configDir); return { ok: false }; }
     const { adapter } = resolved;
 
     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`);
       return { ok: true };
     } catch (err) {
+      safeRelease(releaseActionFn, ticketKey, 'assign', configDir);
       stream.write(formatWriteFailure(ticketKey, err));
       return { ok: false };
     }
@@ -596,19 +646,21 @@ export async function runTicketAssign(cmdArgs, {
     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`);
+  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);
-    recordActionFn(ticketKey, 'assign', { configDir });
     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 };
   }
@@ -776,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,
@@ -803,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 };
   }
@@ -824,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(
@@ -838,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 };
   }
@@ -870,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';
@@ -894,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 };
   }
 }
@@ -956,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,
@@ -1022,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 };
   }
 
@@ -1032,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.
@@ -1045,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

@@ -22,7 +22,11 @@
  *   issueTypesByProject:  {KEY: [{id, name}]},
  *   issueTypesFetchedAt:  {KEY: iso timestamp}  // per-project, either access pattern
  *   assignableUsersByProject:  {KEY: {normalizedQuery: [{accountId, displayName}]}},
- *   assignableUsersFetchedAt:  {KEY: {normalizedQuery: iso timestamp}}
+ *   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
@@ -32,6 +36,20 @@
  * `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';
@@ -105,6 +123,34 @@ export function mergeAssignableUsers(cached, projectKey, query, candidates, fetc
   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.
  */
@@ -127,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, assignableUsersByProject: object, assignableUsersFetchedAt: 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);
@@ -152,6 +198,10 @@ export function readMetadataCache(profileName, configDir = DEFAULT_CONFIG_DIR, t
     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,
   };
@@ -164,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 = {}, assignableUsersByProject = {}, assignableUsersFetchedAt = {}, 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 });
@@ -176,6 +226,10 @@ export function writeMetadataCache(profileName, { projects = [], issueTypesByPro
       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`;
+}