ticketlens 0.23.0 → 0.25.0

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

@@ -54,6 +54,9 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('ticketlens')} recall sync                 Retry any notes stuck in the local queue  ${s.dim('[Team+]')}`,
     `    ${s.brand('ticketlens')} recall settings             Show effective retry-queue settings, fetched live  ${s.dim('[Team+]')}`,
     `    ${s.brand('ticketlens')} mcp                         Start the MCP stdio server for Recall  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} comment ${s.dim('<TICKET-KEY> --body=...')}  Post a comment to the tracker  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} transition ${s.dim('<TICKET-KEY> [--target=... --confirm]')}  Move ticket status  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} assign ${s.dim('<TICKET-KEY> --to=me')}      Assign a ticket to yourself  ${s.dim('[Pro]')}`,
     '',
     `    ${s.brand('ticketlens')} delete ${s.dim('<PROFILE-NAME>')}       Remove a profile`,
     `    ${s.brand('ticketlens')} activate ${s.dim('<KEY>')}              Activate a license key`,
@@ -592,11 +595,14 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     '',
     `  ${s.bold(s.brand('ticketlens'))} ${s.bold('mcp')}  ${s.dim('[Pro]')}`,
     '',
-    `  Start an MCP (Model Context Protocol) stdio server exposing Recall as`,
-    `  native tools — ${s.cyan('recall_add')} and ${s.cyan('recall_search')} — for any MCP-compatible AI`,
-    `  harness, not just Claude Code. Thin adapter over the same code as`,
-    `  ${s.cyan('note add')}/${s.cyan('recall')} above: same Pro gate, same secret scan, same local`,
-    `  vault, same team sync. Long-running — exits when the client closes stdin.`,
+    `  Start an MCP (Model Context Protocol) stdio server exposing Recall and`,
+    `  ticket writes as native tools — ${s.cyan('recall_add')}, ${s.cyan('recall_search')}, ${s.cyan('ticket_comment')},`,
+    `  ${s.cyan('ticket_transition')}, ${s.cyan('ticket_assign')} — for any MCP-compatible AI harness, not just`,
+    `  Claude Code. Thin adapter over the same code as ${s.cyan('note add')}/${s.cyan('recall')}/${s.cyan('comment')}/`,
+    `  ${s.cyan('transition')}/${s.cyan('assign')} above: same Pro gate, same local vault/tracker writes, same`,
+    `  team sync. ${s.cyan('ticket_transition')} is destructive when called with \`target\`+\`confirm: true\`;`,
+    `  ${s.cyan('ticket_assign')} is currently self-assign only.`,
+    `  Long-running — exits when the client closes stdin.`,
     '',
     `  ${s.bold('OPTIONS')}`,
     '',
@@ -623,6 +629,79 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
   stream.write(lines.join('\n') + '\n');
 }
 
+export function printCommentHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('comment')} ${s.dim('TICKET-KEY --body="..."')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Post a comment directly to the ticket in its tracker (Jira/GitHub/Linear). ${s.dim('[Pro]')}`,
+    `  Writes to the real tracker — this is not a local Recall note.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--body')}=${s.dim('TEXT')}    Comment body ${s.dim('(required)')}`,
+    `    ${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 comment PROD-123 --body="Looks good, merging."`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
+export function printTransitionHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('transition')} ${s.dim('TICKET-KEY [--target="..." --confirm]')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Move a ticket to a new status in its tracker (Jira/GitHub/Linear). ${s.dim('[Pro]')}`,
+    `  Called with just a ticket key, lists the tracker's current valid options`,
+    `  without changing anything. Add ${s.brand('--target')} and ${s.brand('--confirm')} together to execute.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--target')}=${s.dim('NAME')}  Target status/transition name ${s.dim('(from the list, case-insensitive)')}`,
+    `    ${s.brand('--confirm')}     Required alongside --target to actually execute`,
+    `    ${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 transition PROD-123`,
+    `    ${s.dim('$')} ticketlens transition PROD-123 --target="Done" --confirm`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
+export function printAssignHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${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.`,
+    '',
+    `  ${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.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens assign PROD-123 --to=me`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
 export function printSwitchHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [

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

@@ -4,7 +4,7 @@
  * Supports v2 (Server/DC) and v3 (Cloud) API versions.
  */
 
-import { adfToText } from './adf-converter.mjs';
+import { adfToText, textToAdf } from './adf-converter.mjs';
 import { lookup as dnsLookup } from 'node:dns/promises';
 
 function toText(value) {
@@ -408,6 +408,122 @@ export async function fetchRemoteLinks(ticketKey, opts = {}) {
     .map(link => ({ url: link.object.url, title: link.object.title ?? null }));
 }
 
+/**
+ * Adds a comment to an issue. Cloud (v3) rejects a plain string body
+ * outright and requires ADF; Server/DC (v2) accepts plain text directly —
+ * same apiVersion branch point every other write/read here already uses.
+ */
+export async function postComment(ticketKey, body, 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 url = `${baseUrl}/rest/api/${apiVersion}/issue/${encodeURIComponent(ticketKey)}/comment`;
+
+  const payload = { body: apiVersion === 3 ? textToAdf(body) : body };
+  const fetchOpts = {
+    method: 'POST',
+    headers: { ...buildAuthHeader(env), 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  };
+  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} commenting on ${ticketKey}`);
+    err.status = response.status;
+    throw err;
+  }
+  const raw = await response.json();
+  return { id: raw.id, url: raw.self ?? null };
+}
+
+/**
+ * Discovers the transitions actually available for this specific issue
+ * right now (workflow-dependent, varies per project/status) — never
+ * hardcode transition names or ids, they aren't stable across projects.
+ */
+export async function getTransitions(ticketKey, 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 url = `${baseUrl}/rest/api/${apiVersion}/issue/${encodeURIComponent(ticketKey)}/transitions`;
+
+  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} fetching transitions for ${ticketKey}`);
+    err.status = response.status;
+    throw err;
+  }
+  const raw = await response.json();
+  return (raw.transitions ?? []).map(t => ({ id: t.id, name: t.name, to: t.to?.name ?? null }));
+}
+
+/**
+ * Executes a transition by id. Callers must resolve the id via
+ * getTransitions() immediately before calling this — never pass a
+ * remembered/stale id, since transitions are workflow- and
+ * time-of-status-dependent (see ticket-command.mjs's re-validation).
+ * A transition requiring a mandatory screen field the caller didn't
+ * supply returns Jira's own 400 with the field list — surfaced as-is,
+ * never silently swallowed or auto-filled.
+ */
+export async function postTransition(ticketKey, transitionId, 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 url = `${baseUrl}/rest/api/${apiVersion}/issue/${encodeURIComponent(ticketKey)}/transitions`;
+
+  const fetchOpts = {
+    method: 'POST',
+    headers: { ...buildAuthHeader(env), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ transition: { id: transitionId } }),
+  };
+  if (timeoutMs) fetchOpts.signal = AbortSignal.timeout(timeoutMs);
+
+  const response = await guardedFetch(url, fetchOpts, { fetcher, lookup, allowPrivateIp });
+  if (!response.ok) {
+    let details;
+    try { details = await response.json(); } catch { /* body not JSON — fall through with no details */ }
+    const err = new Error(`Jira API error ${response.status} transitioning ${ticketKey}`);
+    err.status = response.status;
+    err.details = details;
+    throw err;
+  }
+}
+
+/**
+ * Sets the issue's assignee. `assignee` is sent verbatim — the caller
+ * (jira-adapter.mjs) resolves the right shape for the API version:
+ * `{ accountId }` for Cloud (v3), `{ name }` for Server/DC (v2), since
+ * Cloud has no username concept and Server/DC has no accountId.
+ */
+export async function assignIssue(ticketKey, assignee, 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 url = `${baseUrl}/rest/api/${apiVersion}/issue/${encodeURIComponent(ticketKey)}/assignee`;
+
+  const fetchOpts = {
+    method: 'PUT',
+    headers: { ...buildAuthHeader(env), 'Content-Type': 'application/json' },
+    body: JSON.stringify(assignee),
+  };
+  if (timeoutMs) fetchOpts.signal = AbortSignal.timeout(timeoutMs);
+
+  const response = await guardedFetch(url, fetchOpts, { fetcher, lookup, allowPrivateIp });
+  if (!response.ok) {
+    let details;
+    try { details = await response.json(); } catch { /* body not JSON — fall through with no details */ }
+    const err = new Error(`Jira API error ${response.status} assigning ${ticketKey}`);
+    err.status = response.status;
+    err.details = details;
+    throw err;
+  }
+}
+
 export async function fetchTicket(ticketKey, opts = {}) {
   const { env = process.env, fetcher = globalThis.fetch, lookup = defaultLookupFor(fetcher), depth = 1, apiVersion = 2, timeoutMs = 10_000, expandChangelog = false, allowPrivateIp = false, _visited = new Set(), _currentDepth = 0 } = opts;
   validateBaseUrl(env.JIRA_BASE_URL, allowPrivateIp);

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

@@ -3,12 +3,15 @@
  *
  * A pure transport adapter: parses JSON-RPC 2.0 off stdin, translates
  * `tools/call` arguments into the exact args/dependency shape `runNoteAdd`/
- * `runRecall` already accept, and captures their human-readable `stream`
- * output into the JSON-RPC response instead of a real stream. Zero new
- * validation, licensing, or vault logic — both tools funnel through the
- * same functions the CLI's `note add`/`recall` commands already use, so
- * every existing gate (license, secret scan, structural check, retry
- * queue) applies identically here.
+ * `runRecall`/`runTicketComment`/`runTicketTransitionList`/
+ * `runTicketTransition` already accept, and captures their human-readable
+ * `stream` output into the JSON-RPC response instead of a real stream. Zero
+ * new validation, licensing, or vault logic — every tool funnels through
+ * the same functions the CLI's `note add`/`recall`/`comment`/`transition`
+ * commands already use, so every existing gate (license, secret scan,
+ * structural check, retry queue, cooldown, audit log) applies identically
+ * here. Ticket-writing tools must never import an adapter directly — doing
+ * so would fully bypass the Pro+ gate that lives in ticket-command.mjs.
  *
  * Per the MCP stdio transport spec, the server MUST NOT write anything to
  * stdout that isn't a valid MCP message — every wrapped function's output
@@ -20,6 +23,7 @@ import readline from 'node:readline';
 import { DEFAULT_CONFIG_DIR, getVersion } from './config.mjs';
 import { runNoteAdd } from './note-command.mjs';
 import { runRecall } from './recall-command.mjs';
+import { runTicketComment, runTicketTransitionList, runTicketTransition, runTicketAssign } from './ticket-command.mjs';
 
 const PROTOCOL_VERSION = '2025-11-25';
 
@@ -49,6 +53,43 @@ const TOOLS = [
       required: ['query'],
     },
   },
+  {
+    name: 'ticket_comment',
+    description: 'Post a comment to a ticket in its tracker (Jira/GitHub/Linear). Destructive — writes directly to the live tracker, not a local Recall note. Requires a TicketLens Pro license.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticket: { type: 'string', description: 'Ticket key, e.g. PROJ-123.' },
+        body: { type: 'string', description: 'Comment body.' },
+      },
+      required: ['ticket', 'body'],
+    },
+  },
+  {
+    name: 'ticket_transition',
+    description: 'List or execute a ticket status transition in its tracker (Jira/GitHub/Linear). Called with only `ticket`, lists the tracker\'s current valid options without changing anything. Destructive when `target` and `confirm: true` are both given — requires confirmation and writes directly to the live tracker. Requires a TicketLens Pro license.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticket: { type: 'string', description: 'Ticket key, e.g. PROJ-123.' },
+        target: { type: 'string', description: 'Target status/transition name. Omit to just list the tracker\'s current valid options.' },
+        confirm: { type: 'boolean', description: 'Must be true, alongside `target`, to actually execute the transition — a nudge and audit trail, not just a formality.' },
+      },
+      required: ['ticket'],
+    },
+  },
+  {
+    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.',
+    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.' },
+      },
+      required: ['ticket', 'to'],
+    },
+  },
 ];
 
 function jsonRpcResult(id, result) {
@@ -112,14 +153,73 @@ async function callRecallSearch(args, { configDir, runRecallFn }) {
   return ok ? { content } : { isError: true, content };
 }
 
+/**
+ * `ticket`/`body` become single opaque cmdArgs elements (`--body=${body}`),
+ * same reasoning as buildNoteAddArgs above — a body containing literal
+ * `--confirm` or `--target=` text stays inert since parseFlag only matches
+ * a whole array element via startsWith, never scans inside one.
+ */
+async function callTicketComment(args, { configDir, runTicketCommentFn }) {
+  if (!args.ticket) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: ticket' }] };
+  }
+  if (!args.body) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: body' }] };
+  }
+  const capture = capturingStream();
+  const { ok } = await runTicketCommentFn([args.ticket, `--body=${args.body}`], { configDir, stream: capture });
+  const content = [{ type: 'text', text: capture.text }];
+  return ok ? { content } : { isError: true, content };
+}
+
+/**
+ * No `target` → discovery only, dispatched to the read-only list function —
+ * never touches the mutating path. `target` present → dispatched to the
+ * executing function, which itself still refuses without `confirm: true`
+ * (the MCP layer doesn't pre-empt that check, so the same refusal message
+ * a CLI user sees is what a calling AI harness sees too).
+ */
+async function callTicketTransition(args, { configDir, runTicketTransitionListFn, runTicketTransitionFn }) {
+  if (!args.ticket) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: ticket' }] };
+  }
+  const capture = capturingStream();
+  if (!args.target) {
+    const { ok } = await runTicketTransitionListFn([args.ticket], { configDir, stream: capture });
+    const content = [{ type: 'text', text: capture.text }];
+    return ok ? { content } : { isError: true, content };
+  }
+  const cmdArgs = [args.ticket, `--target=${args.target}`];
+  if (args.confirm === true) cmdArgs.push('--confirm');
+  const { ok } = await runTicketTransitionFn(cmdArgs, { configDir, stream: capture });
+  const content = [{ type: 'text', text: capture.text }];
+  return ok ? { content } : { isError: true, content };
+}
+
+async function callTicketAssign(args, { configDir, runTicketAssignFn }) {
+  if (!args.ticket) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: ticket' }] };
+  }
+  if (!args.to) {
+    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 content = [{ type: 'text', text: capture.text }];
+  return ok ? { content } : { isError: true, content };
+}
+
 async function handleToolsCall(params, deps) {
   const { name, arguments: args = {} } = params ?? {};
   if (name === 'recall_add') return callRecallAdd(args, deps);
   if (name === 'recall_search') return callRecallSearch(args, deps);
+  if (name === 'ticket_comment') return callTicketComment(args, deps);
+  if (name === 'ticket_transition') return callTicketTransition(args, deps);
+  if (name === 'ticket_assign') return callTicketAssign(args, deps);
   return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
 }
 
-async function handleMessage(raw, { configDir, runNoteAddFn, runRecallFn }) {
+async function handleMessage(raw, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn }) {
   let msg;
   try {
     msg = JSON.parse(raw);
@@ -149,7 +249,7 @@ async function handleMessage(raw, { configDir, runNoteAddFn, runRecallFn }) {
 
   if (method === 'tools/call') {
     try {
-      const result = await handleToolsCall(params, { configDir, runNoteAddFn, runRecallFn });
+      const result = await handleToolsCall(params, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn });
       return jsonRpcResult(id, result);
     } catch (err) {
       return jsonRpcError(id ?? null, -32603, `Internal error: ${err.message}`);
@@ -172,6 +272,10 @@ export function runMcpServer({
   stdout = process.stdout,
   runNoteAddFn = runNoteAdd,
   runRecallFn = runRecall,
+  runTicketCommentFn = runTicketComment,
+  runTicketTransitionListFn = runTicketTransitionList,
+  runTicketTransitionFn = runTicketTransition,
+  runTicketAssignFn = runTicketAssign,
 } = {}) {
   // A client can disconnect mid-write (EPIPE) at any time on a long-lived
   // process — an unhandled 'error' event on either stream would otherwise
@@ -191,7 +295,7 @@ export function runMcpServer({
     // never resolving (a dropped rejection isn't a resolution) — the
     // server would hang on shutdown instead of exiting.
     queue = queue.then(async () => {
-      const response = await handleMessage(line, { configDir, runNoteAddFn, runRecallFn });
+      const response = await handleMessage(line, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn });
       if (response) stdout.write(response);
     }).catch(() => {});
   });

package/skills/jtb/scripts/lib/resolve-adapter.mjs

@@ -19,7 +19,7 @@ export function detectTrackerType(baseUrl) {
  * Instantiates the correct tracker adapter for a resolved connection.
  * @param {{ baseUrl: string, auth?: string, email?: string, apiToken?: string, pat?: string }} conn
  * @param {{ fetcher?: Function }} [opts]
- * @returns {{ type: string, fetchTicket: Function, fetchCurrentUser: Function, searchTickets: Function, fetchStatuses: Function }}
+ * @returns {{ type: string, fetchTicket: Function, fetchCurrentUser: Function, searchTickets: Function, fetchStatuses: Function, addComment: Function, getTransitions: Function, transition: Function, assignToSelf: Function }}
  */
 export function resolveAdapter(conn, opts = {}) {
   const type = detectTrackerType(conn?.baseUrl);

package/skills/jtb/scripts/lib/ticket-action-cooldown.mjs

@@ -0,0 +1,72 @@
+/**
+ * Local debounce guard against accidentally firing the same ticket write
+ * twice in quick succession (a flaky agent retry loop, a doubled CLI
+ * invocation, a human hitting enter twice). This is not a security boundary
+ * and not a notification-style cooldown — just enough of a window to catch a
+ * true double-fire without blocking a deliberate follow-up action moments
+ * later.
+ *
+ * Deliberately a separate file from ticket-action-log.mjs (the append-only
+ * audit trail): this file is small and read on every write attempt, so it
+ * must stay O(1) to check. A shared file would force scanning full history
+ * per check, or risk one read-modify-write clobbering the other's data.
+ * Same read-modify-write-no-lock tradeoff already accepted by
+ * recall-queue.mjs for the same reason — low-frequency, single-user CLI.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { writeFileAtomically } from './recall-vault.mjs';
+
+const COOLDOWN_FILE = 'ticket-action-cooldown.json';
+
+/** Default debounce window: long enough to catch a true double-fire, short enough to never block a deliberate follow-up action. */
+export const DEFAULT_COOLDOWN_MS = 10_000;
+
+function cooldownPath(configDir) {
+  return path.join(configDir, COOLDOWN_FILE);
+}
+
+function readCooldowns(configDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cooldownPath(configDir), 'utf8'));
+    return (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function cooldownKey(ticketKey, action) {
+  return `${ticketKey}:${action}`;
+}
+
+/**
+ * @param {string} ticketKey
+ * @param {string} action
+ * @param {{ configDir?: string, cooldownMs?: number, now?: () => number }} [opts]
+ * @returns {{ active: boolean, remainingMs: number }}
+ */
+export function checkCooldown(ticketKey, action, {
+  configDir = DEFAULT_CONFIG_DIR,
+  cooldownMs = DEFAULT_COOLDOWN_MS,
+  now = () => Date.now(),
+} = {}) {
+  const lastAt = readCooldowns(configDir)[cooldownKey(ticketKey, action)];
+  if (!lastAt) return { active: false, remainingMs: 0 };
+
+  const elapsed = now() - new Date(lastAt).getTime();
+  const remainingMs = cooldownMs - elapsed;
+  return remainingMs > 0 ? { active: true, remainingMs } : { active: false, remainingMs: 0 };
+}
+
+/**
+ * @param {string} ticketKey
+ * @param {string} action
+ * @param {{ configDir?: string, now?: () => number }} [opts]
+ */
+export function recordAction(ticketKey, action, { configDir = DEFAULT_CONFIG_DIR, now = () => Date.now() } = {}) {
+  const cooldowns = readCooldowns(configDir);
+  cooldowns[cooldownKey(ticketKey, action)] = new Date(now()).toISOString();
+  writeFileAtomically(cooldownPath(configDir), JSON.stringify(cooldowns));
+}

package/skills/jtb/scripts/lib/ticket-action-log.mjs

@@ -0,0 +1,72 @@
+/**
+ * Append-only forensic audit trail for ticket writes (comment/transition).
+ * Every entry is JSON-serialized on its own line — comment bodies are
+ * attacker/AI-controlled free text, and a raw newline embedded in one could
+ * otherwise forge a fake extra log line (same bug class already fixed once
+ * in this codebase for brief section filenames). JSON.stringify escapes
+ * embedded newlines as \n within the string, so one JSON.parse per line
+ * always recovers exactly one real entry.
+ *
+ * Deliberately a separate file from ticket-action-cooldown.mjs — this one
+ * only ever grows and is never read on the hot path of a write attempt, so
+ * its O(n) full-file nature doesn't matter to normal command latency.
+ *
+ * ticketKey is validated by the caller (ticket-command.mjs, via
+ * TICKET_KEY_PATTERN) before it ever reaches here — this module re-validates
+ * defensively since a log line is a place a malformed key could otherwise do
+ * real damage (path traversal has no surface here since the log file path
+ * never incorporates ticketKey, but a stray literal newline inside an
+ * unvalidated key would reintroduce exactly the forgeable-line risk this
+ * file exists to prevent).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { TICKET_KEY_PATTERN } from './cli.mjs';
+
+const LOG_FILE = 'ticket-action-log.jsonl';
+
+function logPath(configDir) {
+  return path.join(configDir, LOG_FILE);
+}
+
+/**
+ * @param {{ ticketKey: string, action: 'comment'|'transition', actor: string, tracker: string, detail?: object }} entry
+ * @param {{ configDir?: string, now?: () => Date }} [opts]
+ */
+export function logAction({ ticketKey, action, actor, tracker, detail = {} }, {
+  configDir = DEFAULT_CONFIG_DIR,
+  now = () => new Date(),
+} = {}) {
+  if (!TICKET_KEY_PATTERN.test(ticketKey)) {
+    throw new Error(`Refusing to log malformed ticket key: ${JSON.stringify(ticketKey)}`);
+  }
+  const line = JSON.stringify({ ticketKey, action, actor, tracker, detail, at: now().toISOString() });
+  fs.appendFileSync(logPath(configDir), line + '\n', 'utf8');
+}
+
+/**
+ * @param {string} [configDir]
+ * @returns {object[]} parsed entries, oldest first — a corrupt individual
+ *   line is skipped rather than failing the whole read, since this is an
+ *   append-only historical record and one bad line must not hide the rest.
+ */
+export function readActionLog(configDir = DEFAULT_CONFIG_DIR) {
+  let raw;
+  try {
+    raw = fs.readFileSync(logPath(configDir), 'utf8');
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      // Skip a corrupt line — never let one bad append hide the rest of the trail.
+    }
+  }
+  return entries;
+}