ticketlens 0.22.1 → 0.24.0

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,92 @@ 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;
+  }
+}
+
 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-install.mjs

@@ -0,0 +1,92 @@
+/**
+ * Registers `ticketlens mcp` into the current project's `.mcp.json` so the
+ * user doesn't have to hand-write the JSON. Project-scoped only — Claude
+ * Code's MCP config has no global/user-level equivalent (confirmed by
+ * inspecting a real ~/.claude.json: no top-level `mcpServers` key, it's
+ * nested per-project). Never touches ~/.claude.json directly.
+ *
+ * Mirrors hooks-setup.mjs's already-proven safe-merge pattern: malformed
+ * JSON is left untouched (never overwritten), the write is atomic (temp
+ * file + rename — real guarantee on POSIX, still the best available
+ * cross-platform approach on Windows), and every other key in the file is
+ * preserved exactly. Registration itself is never license-gated — same as
+ * `ticketlens mcp`/`note add`/`recall`, which all exist for everyone and
+ * gate only at actual invocation.
+ */
+
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { isLicensed } from './license.mjs';
+import { createStyler } from './ansi.mjs';
+
+const ENTRY_NAME = 'ticketlens';
+
+function readConfig(configPath) {
+  if (!existsSync(configPath)) return { ok: true, config: {} };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    return { ok: false, reason: `${configPath} is not valid JSON — left untouched. Fix or remove it, then retry.` };
+  }
+  // Valid JSON whose top level isn't a plain object (array/null/number/string/
+  // boolean) is still valid to parse — `typeof null === 'object'` and arrays
+  // are objects too, so both need an explicit check, not just "did it parse."
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return { ok: false, reason: `${configPath}'s top level is not a JSON object — left untouched. Fix or remove it, then retry.` };
+  }
+  if (parsed.mcpServers !== undefined && (typeof parsed.mcpServers !== 'object' || parsed.mcpServers === null || Array.isArray(parsed.mcpServers))) {
+    return { ok: false, reason: `${configPath}'s "mcpServers" key is not an object — left untouched. Fix or remove it, then retry.` };
+  }
+  return { ok: true, config: parsed };
+}
+
+/**
+ * @returns {{ written: boolean, dryRun: boolean, path: string, alreadyCorrect?: boolean, reason?: string }}
+ */
+export function mcpInstall({
+  cwd = process.cwd(),
+  isLicensedFn = isLicensed,
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stdout,
+  dryRun = false,
+} = {}) {
+  const configPath = join(cwd, '.mcp.json');
+  const s = createStyler({ isTTY: stream.isTTY });
+
+  const read = readConfig(configPath);
+  if (!read.ok) {
+    stream.write(`  ${s.dim('✗')} ${read.reason}\n`);
+    return { written: false, dryRun, path: configPath, reason: read.reason };
+  }
+
+  const config = read.config;
+  config.mcpServers ??= {};
+  const desired = { command: ENTRY_NAME, args: ['mcp'] };
+  const existing = config.mcpServers[ENTRY_NAME];
+  const alreadyCorrect = existing !== undefined && JSON.stringify(existing) === JSON.stringify(desired);
+  config.mcpServers[ENTRY_NAME] = desired;
+
+  const serialized = JSON.stringify(config, null, 2) + '\n';
+
+  if (dryRun) {
+    stream.write(`  Would write ${configPath}:\n\n${serialized}\n`);
+    return { written: false, dryRun: true, path: configPath, alreadyCorrect };
+  }
+
+  if (alreadyCorrect) {
+    stream.write(`  ${s.dim('✔')} Already registered in ${configPath}\n`);
+  } else {
+    const tmpPath = `${configPath}.${process.pid}.tmp`;
+    writeFileSync(tmpPath, serialized, 'utf8');
+    renameSync(tmpPath, configPath); // atomic on POSIX; best available cross-platform approach on Windows
+    stream.write(`  ${s.brand('✔')} Registered "ticketlens" in ${configPath}\n`);
+  }
+
+  if (!isLicensedFn('pro', configDir)) {
+    stream.write(`  ${s.dim('Note: recall_add/recall_search require a Pro license — see')} ${s.cyan('ticketlens license')}${s.dim('.')}\n`);
+  }
+
+  return { written: !alreadyCorrect, dryRun: false, path: configPath, alreadyCorrect };
+}

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 } from './ticket-command.mjs';
 
 const PROTOCOL_VERSION = '2025-11-25';
 
@@ -49,6 +53,31 @@ 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'],
+    },
+  },
 ];
 
 function jsonRpcResult(id, result) {
@@ -112,14 +141,59 @@ 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 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);
   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 }) {
   let msg;
   try {
     msg = JSON.parse(raw);
@@ -149,7 +223,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 });
       return jsonRpcResult(id, result);
     } catch (err) {
       return jsonRpcError(id ?? null, -32603, `Internal error: ${err.message}`);
@@ -172,6 +246,9 @@ export function runMcpServer({
   stdout = process.stdout,
   runNoteAddFn = runNoteAdd,
   runRecallFn = runRecall,
+  runTicketCommentFn = runTicketComment,
+  runTicketTransitionListFn = runTicketTransitionList,
+  runTicketTransitionFn = runTicketTransition,
 } = {}) {
   // 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 +268,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 });
       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 }}
  */
 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;
+}