ticketlens 0.39.0 → 0.39.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.39.0",
+  "version": "0.39.2",
   "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/ticket-action-cooldown.mjs

@@ -70,3 +70,74 @@ export function recordAction(ticketKey, action, { configDir = DEFAULT_CONFIG_DIR
   cooldowns[cooldownKey(ticketKey, action)] = new Date(now()).toISOString();
   writeFileAtomically(cooldownPath(configDir), JSON.stringify(cooldowns));
 }
+
+const LOCK_STALE_MS = 5_000;
+const LOCK_POLL_MS = 15;
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Cross-process mutex around the cooldown file's read-modify-write, via an
+ * O_EXCL lock file. Fails closed: if the lock cannot be taken in `lockWaitMs`
+ * the caller gets an error, never an unguarded claim. A lock older than
+ * LOCK_STALE_MS belongs to a crashed process and is cleared.
+ */
+function withLock(configDir, lockWaitMs, fn) {
+  fs.mkdirSync(configDir, { recursive: true });
+  const lockPath = `${cooldownPath(configDir)}.lock`;
+  const deadline = Date.now() + lockWaitMs;
+  let fd;
+  while (fd === undefined) {
+    try {
+      fd = fs.openSync(lockPath, 'wx');
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        if (Date.now() - fs.statSync(lockPath).mtimeMs > LOCK_STALE_MS) { fs.rmSync(lockPath, { force: true }); continue; }
+      } catch { /* lock vanished between exists-check and stat — just retry */ }
+      if (Date.now() > deadline) throw new Error('cooldown lock busy — another ticketlens process holds it');
+      sleepSync(LOCK_POLL_MS);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    fs.closeSync(fd);
+    fs.rmSync(lockPath, { force: true });
+  }
+}
+
+/**
+ * Atomic check-and-set: unlike checkCooldown-then-recordAction, two processes
+ * cannot both pass the check. Use before a write that must never double-fire
+ * (billable time) — claim BEFORE the network call, `releaseAction` on a
+ * definite failure so a corrected retry isn't blocked.
+ *
+ * @returns {{ claimed: boolean, remainingMs: number }}
+ */
+export function claimAction(ticketKey, action, {
+  configDir = DEFAULT_CONFIG_DIR,
+  cooldownMs = DEFAULT_COOLDOWN_MS,
+  now = () => Date.now(),
+  lockWaitMs = 2_000,
+} = {}) {
+  return withLock(configDir, lockWaitMs, () => {
+    const status = checkCooldown(ticketKey, action, { configDir, cooldownMs, now });
+    if (status.active) return { claimed: false, remainingMs: status.remainingMs };
+    recordAction(ticketKey, action, { configDir, now });
+    return { claimed: true, remainingMs: 0 };
+  });
+}
+
+/** Frees a claim. A key that was never claimed is a no-op. */
+export function releaseAction(ticketKey, action, { configDir = DEFAULT_CONFIG_DIR, lockWaitMs = 2_000 } = {}) {
+  withLock(configDir, lockWaitMs, () => {
+    const cooldowns = readCooldowns(configDir);
+    const key = cooldownKey(ticketKey, action);
+    if (!(key in cooldowns)) return;
+    const { [key]: _released, ...rest } = cooldowns;
+    writeFileAtomically(cooldownPath(configDir), JSON.stringify(rest));
+  });
+}

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

@@ -20,7 +20,7 @@ import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { isLicensed } from './license.mjs';
 import { resolveConnection } from './profile-resolver.mjs';
 import { resolveAdapter } from './resolve-adapter.mjs';
-import { checkCooldown, recordAction } from './ticket-action-cooldown.mjs';
+import { checkCooldown, recordAction, claimAction, releaseAction } from './ticket-action-cooldown.mjs';
 import { logAction } from './ticket-action-log.mjs';
 import { TICKET_KEY_PATTERN, normalizeTicketKey } from './cli.mjs';
 import { createStyler, sanitizeUntrustedText } from './ansi.mjs';
@@ -39,6 +39,9 @@ const UNCONFIRMED_WINDOW_MS = 10 * 60 * 1000;
 const USAGE = 'Usage: ticketlens worklog KEY=DURATION [KEY=DURATION ...] [--comment="..."] [--started=ISO] [--profile=NAME] --confirm\n';
 const COMMENT_PREVIEW_CHARS = 60;
 
+/** Outcomes where the POST may have landed even though the caller saw a failure. */
+const AMBIGUOUS_KINDS = new Set(['network-or-timeout', 'server-error']);
+
 const invalid = (error) => ({ error });
 const refused = (reason) => ({ ok: false, reason, results: [] });
 const fromResult = (result, valueKey) => (result.ok ? { value: result[valueKey] } : invalid(result.error));
@@ -167,22 +170,26 @@ function recordBookkeeping(item, result, { configDir, recordActionFn, logActionF
 /** Tracker text is untrusted: strip terminal control characters per line, keeping the line structure. */
 const safeLines = (text) => text.split('\n').map(sanitizeUntrustedText).join('\n');
 
+const recentSkip = (ticket, remainingMs) => ({
+  reason: 'recent',
+  text: `  Skipped ${ticket} — a worklog was already logged just now and is not repeated (blocked ${Math.ceil(remainingMs / 1000)}s more). Check the ticket before logging again.\n`,
+});
+
 /** Checked before every write: a recent worklog, or a recent write whose outcome is still unknown. */
 function skipReason(item, { configDir, checkCooldownFn }) {
   const unconfirmed = checkCooldownFn(item.ticket, 'worklog-unconfirmed', { configDir, cooldownMs: UNCONFIRMED_WINDOW_MS });
   if (unconfirmed.active) {
-    return `  Skipped ${item.ticket} — an earlier write to it ended without a confirmed result (timeout or server error) ${Math.ceil(unconfirmed.remainingMs / 60000)}m ago and may have already landed. Check the ticket in Jira before logging again.\n`;
+    return { reason: 'unconfirmed', text: `  Skipped ${item.ticket} — an earlier write to it ended without a confirmed result (timeout or server error) and may have already landed (blocked ${Math.ceil(unconfirmed.remainingMs / 60000)}m more). Check the ticket in Jira before logging again.\n` };
   }
   const recent = checkCooldownFn(item.ticket, 'worklog', { configDir });
   if (recent.active) {
-    return `  Skipped ${item.ticket} — a worklog was already logged ${Math.ceil(recent.remainingMs / 1000)}s ago and is not repeated. Check the ticket before logging again.\n`;
+    return recentSkip(item.ticket, recent.remainingMs);
   }
   return null;
 }
 
 /** Timeout / 5xx: the POST may have landed. Leave a long cooldown and an audit line so a retry can't silently double-bill. */
 function recordUnconfirmed(item, classification, { configDir, recordActionFn, logActionFn, actor, stream, source }) {
-  if (classification.kind !== 'network-or-timeout' && classification.kind !== 'server-error') return;
   try {
     logActionFn({ ticketKey: item.ticket, action: 'worklog-unconfirmed', actor, tracker: item.adapter.type, detail: { seconds: item.seconds, started: item.started, kind: classification.kind, source } }, { configDir });
     recordActionFn(item.ticket, 'worklog-unconfirmed', { configDir });
@@ -191,12 +198,31 @@ function recordUnconfirmed(item, classification, { configDir, recordActionFn, lo
   }
 }
 
+/**
+ * Claims the ticket's cooldown atomically BEFORE the POST — a check-then-write
+ * lets two parallel processes both pass the check and both bill the time.
+ * @returns {{ reason: string, text: string } | null} a skip, or null when the claim is ours
+ */
+function claimOrSkip(item, { configDir, claimActionFn }) {
+  try {
+    const claim = claimActionFn(item.ticket, 'worklog', { configDir });
+    return claim.claimed ? null : recentSkip(item.ticket, claim.remainingMs);
+  } catch (err) {
+    return { reason: 'lock', text: `  ${item.ticket} not written — could not take the cooldown lock (${sanitizeUntrustedText(String(err.message))}). Nothing was sent; safe to retry.\n` };
+  }
+}
+
+/** A definite rejection sent nothing that landed: free the claim so a corrected retry isn't blocked. */
+function releaseClaim(item, { configDir, releaseActionFn }) {
+  try { releaseActionFn(item.ticket, 'worklog', { configDir }); } catch { /* best effort — the claim expires by itself */ }
+}
+
 async function logOne(item, ctx) {
   const { stream } = ctx;
-  const skip = skipReason(item, ctx);
+  const skip = skipReason(item, ctx) ?? claimOrSkip(item, ctx);
   if (skip) {
-    stream.write(skip);
-    return { ticket: item.ticket, status: 'skipped', reason: 'cooldown' };
+    stream.write(skip.text);
+    return { ticket: item.ticket, status: 'skipped', reason: skip.reason };
   }
   const entry = { timeSpentSeconds: item.seconds, started: item.started, ...(item.comment !== undefined && { comment: item.comment }) };
   let result;
@@ -205,7 +231,8 @@ async function logOne(item, ctx) {
   } catch (err) {
     const classification = classifyWriteFailure(err);
     stream.write(safeLines(formatWriteFailure(item.ticket, err)));
-    recordUnconfirmed(item, classification, ctx);
+    if (AMBIGUOUS_KINDS.has(classification.kind)) recordUnconfirmed(item, classification, ctx);
+    else releaseClaim(item, ctx);
     return { ticket: item.ticket, status: 'failed', error: sanitizeUntrustedText(String(err.message)), kind: classification.kind, httpStatus: err.status };
   }
   const s = createStyler({ isTTY: stream.isTTY });
@@ -221,13 +248,23 @@ function haltReason(result) {
   return null;
 }
 
-/** Names what landed and what to retry, so a caller (often an AI) never re-sends a worklog that already went through. */
+/**
+ * Sorts every result into exactly one of three actions for the caller (often an
+ * AI): already landed (never repeat), unknown outcome (check Jira first), or
+ * safe to retry. A ticket skipped as "already logged" must never land under
+ * retry — a blind retry after the 10s debounce would double-bill it.
+ */
 function writeBatchSummary(results, stream) {
-  const logged = results.filter(r => r.status === 'logged').map(r => r.ticket);
-  const pending = results.filter(r => r.status !== 'logged').map(r => r.ticket);
-  stream.write(`\n  Logged ${logged.length} of ${results.length} worklogs.\n`);
-  if (logged.length && pending.length) stream.write(`  Already logged (do not repeat): ${logged.join(', ')}.\n`);
-  if (pending.length) stream.write(`  Retry only: ${pending.join(', ')}.\n`);
+  const isLanded = (r) => r.status === 'logged' || r.reason === 'recent';
+  const isUnknown = (r) => r.reason === 'unconfirmed' || (r.status === 'failed' && AMBIGUOUS_KINDS.has(r.kind));
+  const names = (pick) => results.filter(pick).map(r => r.ticket).join(', ');
+  const landed = names(isLanded);
+  const unknown = names(isUnknown);
+  const retry = names(r => !isLanded(r) && !isUnknown(r));
+  stream.write(`\n  Logged ${results.filter(r => r.status === 'logged').length} of ${results.length} worklogs.\n`);
+  if (landed && (unknown || retry)) stream.write(`  Already logged (do not repeat): ${landed}.\n`);
+  if (unknown) stream.write(`  Check in Jira before logging again (may have landed): ${unknown}.\n`);
+  if (retry) stream.write(`  Retry only: ${retry}.\n`);
 }
 
 async function logAll(items, ctx) {
@@ -266,6 +303,8 @@ export async function runTicketWorklogEntries(entries, {
   resolveConnectionFn = resolveConnection,
   resolveAdapterFn = resolveAdapter,
   checkCooldownFn = checkCooldown,
+  claimActionFn = claimAction,
+  releaseActionFn = releaseAction,
   recordActionFn = recordAction,
   logActionFn = logAction,
   actor = os.userInfo().username,
@@ -282,7 +321,7 @@ export async function runTicketWorklogEntries(entries, {
     writePreview(resolved, { stream, cliHints });
     return refused('confirm-required');
   }
-  return logAll(resolved, { configDir, checkCooldownFn, recordActionFn, logActionFn, actor, stream, source: cliHints ? 'cli' : 'mcp' });
+  return logAll(resolved, { configDir, checkCooldownFn, claimActionFn, releaseActionFn, recordActionFn, logActionFn, actor, stream, source: cliHints ? 'cli' : 'mcp' });
 }
 
 function parsePair(arg) {