ticketlens 0.38.16 → 0.38.18

package/README.md

@@ -44,6 +44,7 @@
   - [Recall](#recall)
   - [Comment, Transition, Assign, Duplicates, Link, Update & Create](#comment-transition-assign-duplicates-link-update--create)
   - [Response-Time Stats](#response-time-stats)
+  - [Doctor](#doctor)
   - [Custom Attention Rules](#custom-attention-rules)
   - [Login](#login)
   - [License](#license)
@@ -525,6 +526,20 @@ A one-line summary footer is also appended automatically to `ticketlens triage`
 
 ---
 
+### Doctor
+
+```bash
+ticketlens doctor                        # Diagnose profile/license/connectivity/cache/queue problems
+ticketlens doctor --fix                  # Attempt safe automatic fixes (license revalidation, corrupt cache cleanup, queue flush)
+ticketlens doctor --profile=acme         # Scope checks to a single profile
+ticketlens doctor --format=json          # JSON output for scripting/piping
+ticketlens doctor --format=json | jq '.ok'
+```
+
+Runs five checks — profile configuration, license freshness, tracker connectivity, attachment cache health, and the Recall sync queue — and reports pass/fail with an actionable hint per failure, instead of a raw stack trace. Free tier, fully unrestricted; no license required.
+
+---
+
 ### Custom Attention Rules
 
 Add an `attentionRules` array to any profile in `~/.ticketlens/profiles.json` to override how `ticketlens triage` scores specific tickets:
@@ -801,6 +816,12 @@ ticketlens stats --profile=acme              # Metrics for a specific profile
 ticketlens stats --days=14                   # Extend lookback window (Pro, max 30)
 ticketlens stats --format=json               # JSON output for scripting
 
+# ── Doctor ────────────────────────────────────────────────────────────────────
+ticketlens doctor                             # Diagnose profile/license/connectivity/cache/queue problems
+ticketlens doctor --fix                       # Attempt safe automatic fixes
+ticketlens doctor --profile=acme             # Scope checks to a single profile
+ticketlens doctor --format=json               # JSON output for scripting/piping
+
 # ── Compliance ────────────────────────────────────────────────────────────────
 ticketlens compliance <TICKET-KEY>            # Check ticket requirements against local diff [Pro/Free 3/mo]
 ticketlens ledger                             # View local compliance audit ledger [Pro]

package/bin/ticketlens.mjs

@@ -18,6 +18,7 @@ import { run as runConfig } from '../skills/jtb/scripts/lib/config-wizard.mjs';
 import { activateLicense, checkLicense, revalidateIfStale, isLicensed, showUpgradePrompt, readLicense } from '../skills/jtb/scripts/lib/license.mjs';
 import { deleteProfile, loadProfiles, saveCredentialKey } from '../skills/jtb/scripts/lib/profile-resolver.mjs';
 import { run as runCache } from '../skills/jtb/scripts/lib/cache-manager.mjs';
+import { runDoctor } from '../skills/jtb/scripts/lib/doctor-command.mjs';
 import {
   printHelp, printProfiles, printHistoryHelp,
   printLoginHelp, printLogoutHelp, printSyncHelp,
@@ -26,7 +27,7 @@ import {
   printInitHelp, printSwitchHelp, printConfigHelp,
   printReviewHelp, printStandupHelp, printUpdateSkillHelp,
   printComplianceHelp, printLedgerHelp, printPrHelp, printInstallHooksHelp,
-  printCollisionsHelp, printStatsHelp,
+  printCollisionsHelp, printStatsHelp, printDoctorHelp,
   printCloudKeysHelp,
   printNoteHelp, printRecallHelp, printMcpHelp,
   printCommentHelp, printTransitionHelp, printAssignHelp, printDuplicatesHelp, printLinkHelp, printUpdateHelp, printCreateHelp,
@@ -175,6 +176,17 @@ switch (command) {
     break;
   }
 
+  case 'doctor': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printDoctorHelp(); break; }
+    runDoctor(cmdArgs).then(({ ok }) => {
+      if (!ok) process.exitCode = 1;
+    }).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
   case 'init':
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printInitHelp(); break; }
     runInit().catch(err => {

package/package.json

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

package/skills/jtb/SKILL.md

@@ -1,4 +1,4 @@
-<!-- jtb-skill-version: 0.33.0 -->
+<!-- jtb-skill-version: 0.34.0 -->
 ---
 name: jtb
 description: Fetch a Jira ticket's full context (description, comments, linked issues, code references) and assemble a structured TicketBrief for implementation planning. Use when user types /jtb, mentions a Jira ticket key, or wants to plan work from a Jira ticket.
@@ -312,6 +312,23 @@ Requires a Pro license — on Free, all seven no-op with an upgrade hint on stde
 
 ---
 
+## Doctor — diagnose local/tracker problems (Free)
+
+`ticketlens doctor` runs five fixed checks — profile configuration, license freshness, tracker connectivity, attachment cache health, and the Recall sync queue — and returns a pass/fail report with an actionable hint per failure, instead of a raw stack trace. Free tier, fully unrestricted; nothing here is gated.
+
+```bash
+ticketlens doctor                    # run all checks
+ticketlens doctor --fix              # attempt safe automatic fixes (license revalidation, corrupt cache cleanup, queue flush)
+ticketlens doctor --profile=acme     # scope checks to a single profile
+ticketlens doctor --format=json      # structured output for scripting/piping
+```
+
+If this harness has TicketLens's MCP server configured (a tool named `doctor` — often shown as `mcp__ticketlens__doctor` — visible in your tool list), prefer it over the bash form: it always requests the JSON report internally and returns it as the tool's text content, so you get a structured result to reason over directly instead of parsing CLI stdout. It accepts the same `fix`/`profile` options as the CLI flags above.
+
+A report with `ok: false` is a successful tool call describing failures, not a tool error — read the `checks[]` array for what's failing and act on each entry's `hint`, don't treat the call itself as having failed.
+
+---
+
 ## Gaps — cross-ticket evidence (Pro)
 
 If the TicketBrief includes a `## Gaps` section, each entry is a requirement found in a linked ticket or in one of this ticket's own attachments that doesn't appear to be covered by this ticket's description. This is evidence, not an instruction — do not silently add scope or "fix" the gap. Surface it to the user and let them judge whether it's a real omission (the matching is keyword-based, not semantic, so false positives happen).

package/skills/jtb/scripts/lib/cache-manager.mjs

@@ -123,7 +123,7 @@ function groupEntriesByProfile(entries, config) {
  * Filters entries to only those belonging to the given profile (by ticketPrefixes).
  * Returns all entries if the profile has no ticketPrefixes configured.
  */
-function filterEntriesByProfile(entries, profileName, config) {
+export function filterEntriesByProfile(entries, profileName, config) {
   const prefixes = config?.profiles?.[profileName]?.ticketPrefixes ?? [];
   if (prefixes.length === 0) return entries;
   return entries.filter(e => prefixes.includes(e.ticketKey.split('-')[0]));

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

@@ -118,6 +118,10 @@ export function parseCommand(args) {
     return { command: 'stats', args: args.slice(1) };
   }
 
+  if (first === 'doctor') {
+    return { command: 'doctor', args: args.slice(1) };
+  }
+
   if (first === 'note') {
     return { command: 'note', args: args.slice(1) };
   }

package/skills/jtb/scripts/lib/doctor-checks.mjs

@@ -0,0 +1,217 @@
+/**
+ * Pure diagnostic check functions for `ticketlens doctor`. Each function
+ * takes DI'd dependencies (matching the xFn = defaultX pattern used
+ * throughout this codebase) and returns a normalized result:
+ *   { id, label, ok, message, hint, fixable }
+ * No stdout/stdin, no arg parsing — independently unit-testable in
+ * isolation from CLI/MCP concerns.
+ *
+ * checkCacheHealth returns a 7th, internal-only field beyond the six
+ * above — `corruptEntries` — consumed only by doctor-command.mjs's
+ * `--fix` step to know which local files to delete. It is stripped
+ * before any public (CLI plain/JSON or MCP) output.
+ */
+
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { resolveProfile, loadCredentials, loadProfiles } from './profile-resolver.mjs';
+import { checkLicense, GRACE_DAYS } from './license.mjs';
+import { resolveAdapter } from './resolve-adapter.mjs';
+import { classifyError } from './error-classifier.mjs';
+import { testConnections } from './connection-tester.mjs';
+import { formatSize } from './attachment-downloader.mjs';
+import { getCacheEntries, filterEntriesByProfile } from './cache-manager.mjs';
+import { readQueue } from './recall-queue.mjs';
+
+const NOOP_STREAM = { write: () => true };
+
+export function checkProfileConfig({
+  configDir = DEFAULT_CONFIG_DIR,
+  profileName = null,
+  cwd = process.cwd(),
+  resolveProfileFn = resolveProfile,
+  loadCredentialsFn = loadCredentials,
+} = {}) {
+  const profile = resolveProfileFn(null, { profileName, configDir, cwd });
+
+  if (!profile) {
+    return {
+      id: 'profile-config', label: 'Profile configuration', ok: false,
+      message: profileName ? `Profile "${profileName}" not found.` : 'No profile configured.',
+      hint: profileName ? 'Run `ticketlens profiles` to see available profiles.' : 'Run `ticketlens init` to set up a profile.',
+      fixable: false,
+    };
+  }
+
+  if (!profile.baseUrl) {
+    return {
+      id: 'profile-config', label: 'Profile configuration', ok: false,
+      message: `Profile "${profile.name}" has no baseUrl configured.`,
+      hint: `Run \`ticketlens config --profile=${profile.name}\` to fix it.`,
+      fixable: false,
+    };
+  }
+
+  const creds = loadCredentialsFn(configDir)[profile.name] || {};
+  if (!creds.apiToken && !creds.pat) {
+    return {
+      id: 'profile-config', label: 'Profile configuration', ok: false,
+      message: `Profile "${profile.name}" has no credentials stored.`,
+      hint: `Run \`ticketlens config --profile=${profile.name}\` to add an API token or PAT.`,
+      fixable: false,
+    };
+  }
+
+  return {
+    id: 'profile-config', label: 'Profile configuration', ok: true,
+    message: `Profile "${profile.name}" resolves with a baseUrl and stored credentials.`,
+    hint: null, fixable: false,
+  };
+}
+
+export function checkLicenseFreshness({
+  configDir = DEFAULT_CONFIG_DIR,
+  checkLicenseFn = checkLicense,
+} = {}) {
+  const status = checkLicenseFn(configDir);
+
+  if (!status.key) {
+    return {
+      id: 'license-freshness', label: 'License freshness', ok: true,
+      message: 'Free tier — no license to validate.', hint: null, fixable: false,
+    };
+  }
+
+  if (status.expired) {
+    return {
+      id: 'license-freshness', label: 'License freshness', ok: false,
+      message: 'License expired.',
+      hint: 'Run `ticketlens activate <KEY>` to renew.', fixable: true,
+    };
+  }
+
+  const daysSinceVal = status.validatedAt
+    ? (Date.now() - new Date(status.validatedAt).getTime()) / 86400000
+    : Infinity;
+
+  if (daysSinceVal > GRACE_DAYS) {
+    return {
+      id: 'license-freshness', label: 'License freshness', ok: false,
+      message: `Not revalidated in over ${GRACE_DAYS} days.`,
+      hint: 'Run `ticketlens doctor --fix` to revalidate now.', fixable: true,
+    };
+  }
+
+  return {
+    id: 'license-freshness', label: 'License freshness', ok: true,
+    message: `${status.tier} license active, last validated ${Math.floor(daysSinceVal)} day(s) ago.`,
+    hint: null, fixable: false,
+  };
+}
+
+export async function checkConnectivity({
+  configDir = DEFAULT_CONFIG_DIR,
+  profileName = null,
+  cwd = process.cwd(),
+  resolveProfileFn = resolveProfile,
+  loadCredentialsFn = loadCredentials,
+  resolveAdapterFn = resolveAdapter,
+  classifyErrorFn = classifyError,
+  testConnectionsFn = testConnections,
+} = {}) {
+  if (profileName) {
+    const profile = resolveProfileFn(null, { profileName, configDir, cwd });
+    if (!profile) {
+      return {
+        id: 'connectivity', label: 'Tracker connectivity', ok: false,
+        message: `Profile "${profileName}" not found.`, hint: null, fixable: false,
+      };
+    }
+    const creds = loadCredentialsFn(configDir)[profile.name] || {};
+    const conn = {
+      baseUrl: profile.baseUrl, auth: profile.auth, email: profile.email,
+      apiToken: creds.apiToken, pat: creds.pat, allowPrivateIp: profile.allowPrivateIp,
+    };
+    try {
+      await resolveAdapterFn(conn).fetchCurrentUser();
+      return {
+        id: 'connectivity', label: 'Tracker connectivity', ok: true,
+        message: `Profile "${profile.name}" connected successfully.`, hint: null, fixable: false,
+      };
+    } catch (err) {
+      const classified = classifyErrorFn(err, { baseUrl: conn.baseUrl, profileName: profile.name });
+      return {
+        id: 'connectivity', label: 'Tracker connectivity', ok: false,
+        message: classified.message, hint: classified.hint, fixable: false,
+      };
+    }
+  }
+
+  const { results, failedCount } = await testConnectionsFn({ configDir, stream: NOOP_STREAM, resolveAdapterFn });
+  if (results.length === 0) {
+    return {
+      id: 'connectivity', label: 'Tracker connectivity', ok: true,
+      message: 'No profiles configured — nothing to test.', hint: null, fixable: false,
+    };
+  }
+  const summary = results.map(r => r.ok ? `${r.name}: ok` : `${r.name}: ${r.error}`).join('; ');
+  return {
+    id: 'connectivity', label: 'Tracker connectivity',
+    ok: failedCount === 0,
+    message: failedCount === 0
+      ? `All ${results.length} profile(s) connected successfully.`
+      : `${failedCount}/${results.length} profile(s) failed to connect.`,
+    hint: failedCount === 0 ? null : summary,
+    fixable: false,
+  };
+}
+
+export function checkCacheHealth({
+  configDir = DEFAULT_CONFIG_DIR,
+  profileName = null,
+  getCacheEntriesFn = getCacheEntries,
+  loadProfilesFn = loadProfiles,
+  filterEntriesByProfileFn = filterEntriesByProfile,
+} = {}) {
+  let entries = getCacheEntriesFn(configDir);
+  if (profileName) {
+    entries = filterEntriesByProfileFn(entries, profileName, loadProfilesFn(configDir));
+  }
+
+  const corrupt = entries.filter(e => e.size === 0);
+  if (corrupt.length === 0) {
+    const totalSize = entries.reduce((sum, e) => sum + e.size, 0);
+    return {
+      id: 'cache-health', label: 'Attachment cache', ok: true,
+      message: entries.length === 0
+        ? 'No cached files.'
+        : `${entries.length} cached file(s), ${formatSize(totalSize)}, none corrupt.`,
+      hint: null, fixable: false, corruptEntries: [],
+    };
+  }
+
+  return {
+    id: 'cache-health', label: 'Attachment cache', ok: false,
+    message: `${corrupt.length} corrupt (0-byte) cached file(s) found.`,
+    hint: 'Run `ticketlens doctor --fix` to remove them.',
+    fixable: true, corruptEntries: corrupt,
+  };
+}
+
+export function checkRecallQueue({
+  configDir = DEFAULT_CONFIG_DIR,
+  readQueueFn = readQueue,
+} = {}) {
+  const entries = readQueueFn(configDir);
+  if (entries.length === 0) {
+    return {
+      id: 'recall-queue', label: 'Recall sync queue', ok: true,
+      message: 'No notes pending sync.', hint: null, fixable: false,
+    };
+  }
+  return {
+    id: 'recall-queue', label: 'Recall sync queue', ok: false,
+    message: `${entries.length} note(s) pending sync.`,
+    hint: 'Run `ticketlens doctor --fix` to retry now, or `ticketlens recall sync`.',
+    fixable: true,
+  };
+}

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

@@ -0,0 +1,145 @@
+/**
+ * Implements `tl doctor`. Runs a fixed set of diagnostic checks
+ * (doctor-checks.mjs) and reports pass/fail with hints. Free tier,
+ * fully unrestricted.
+ */
+
+import fs from 'node:fs';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { handleUnknownFlags } from './arg-validator.mjs';
+import { createStyler } from './ansi.mjs';
+import {
+  checkProfileConfig, checkLicenseFreshness, checkConnectivity,
+  checkCacheHealth, checkRecallQueue,
+} from './doctor-checks.mjs';
+import { revalidateLicense } from './license.mjs';
+import { flushQueue } from './recall-queue.mjs';
+import { readCliToken } from './cli-auth.mjs';
+
+const KNOWN_FLAGS = ['--format=', '--fix', '--profile=', '--help', '-h'];
+
+function renderPlain(checks, { fixed, skipped, stream }) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  stream.write('\n');
+  for (const check of checks) {
+    const icon = check.ok ? s.green('✔') : s.red('✖');
+    stream.write(`  ${icon} ${check.label}: ${check.message}\n`);
+    if (!check.ok && check.hint) stream.write(`      ${s.dim(check.hint)}\n`);
+  }
+  if (fixed.length > 0) {
+    stream.write(`\n  ${s.green('Fixed:')} ${fixed.join(', ')}\n`);
+  }
+  if (skipped.length > 0) {
+    stream.write(`\n  ${s.yellow('Skipped:')}\n`);
+    for (const sk of skipped) stream.write(`    ${sk.id}: ${sk.reason}\n`);
+  }
+  stream.write('\n');
+}
+
+async function applyFixes(rawResults, {
+  configDir, profileName, format, stream,
+  revalidateLicenseFn, checkLicenseFreshnessFn,
+  unlinkFn, checkCacheHealthFn,
+  flushQueueFn, checkRecallQueueFn, readCliTokenFn,
+}) {
+  const fixed = [];
+  const skipped = [];
+  const byId = Object.fromEntries(rawResults.map(r => [r.id, r]));
+
+  if (byId['license-freshness'] && !byId['license-freshness'].ok && byId['license-freshness'].fixable) {
+    if (format === 'plain') stream.write('Revalidating license...\n');
+    await revalidateLicenseFn({ configDir });
+    const recheck = checkLicenseFreshnessFn({ configDir });
+    byId['license-freshness'] = recheck;
+    if (recheck.ok) fixed.push('license-freshness');
+  }
+
+  if (byId['cache-health'] && !byId['cache-health'].ok && byId['cache-health'].fixable) {
+    if (format === 'plain') stream.write('Clearing corrupt cache entries...\n');
+    for (const entry of byId['cache-health'].corruptEntries ?? []) {
+      try { unlinkFn(entry.localPath); } catch { /* already gone */ }
+    }
+    const recheck = checkCacheHealthFn({ configDir, profileName });
+    byId['cache-health'] = recheck;
+    if (recheck.ok) fixed.push('cache-health');
+  }
+
+  if (byId['recall-queue'] && !byId['recall-queue'].ok && byId['recall-queue'].fixable) {
+    const cliToken = readCliTokenFn(configDir);
+    if (!cliToken) {
+      skipped.push({ id: 'recall-queue', reason: 'Not logged in — run `ticketlens login` first.' });
+    } else {
+      if (format === 'plain') stream.write('Flushing recall queue...\n');
+      await flushQueueFn({ cliToken, configDir });
+      const recheck = checkRecallQueueFn({ configDir });
+      byId['recall-queue'] = recheck;
+      if (recheck.ok) fixed.push('recall-queue');
+    }
+  }
+
+  return { results: Object.values(byId), fixed, skipped };
+}
+
+export async function runDoctor(args, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  out = process.stdout,
+  cwd = process.cwd(),
+  checkProfileConfigFn = checkProfileConfig,
+  checkLicenseFreshnessFn = checkLicenseFreshness,
+  checkConnectivityFn = checkConnectivity,
+  checkCacheHealthFn = checkCacheHealth,
+  checkRecallQueueFn = checkRecallQueue,
+  revalidateLicenseFn = revalidateLicense,
+  unlinkFn = (p) => fs.unlinkSync(p),
+  flushQueueFn = flushQueue,
+  readCliTokenFn = readCliToken,
+} = {}) {
+  const validated = await handleUnknownFlags(args, KNOWN_FLAGS, { stream });
+  if (validated === null) return { ok: false };
+
+  const formatArg = validated.find(a => a.startsWith('--format='));
+  const format = formatArg ? formatArg.split('=')[1] : 'plain';
+  if (format !== 'plain' && format !== 'json') {
+    stream.write(`Error: --format must be plain or json, got: ${format}\n`);
+    return { ok: false };
+  }
+
+  const profileArg = validated.find(a => a.startsWith('--profile='));
+  const profileName = profileArg ? profileArg.split('=')[1] : null;
+  const shouldFix = validated.includes('--fix');
+
+  const rawResults = [
+    checkProfileConfigFn({ configDir, profileName, cwd }),
+    checkLicenseFreshnessFn({ configDir }),
+    await checkConnectivityFn({ configDir, profileName, cwd }),
+    checkCacheHealthFn({ configDir, profileName }),
+    checkRecallQueueFn({ configDir }),
+  ];
+
+  let fixed = [];
+  let skipped = [];
+  let finalResults = rawResults;
+  if (shouldFix) {
+    const applied = await applyFixes(rawResults, {
+      configDir, profileName, format, stream,
+      revalidateLicenseFn, checkLicenseFreshnessFn,
+      unlinkFn, checkCacheHealthFn,
+      flushQueueFn, checkRecallQueueFn, readCliTokenFn,
+    });
+    finalResults = applied.results;
+    fixed = applied.fixed;
+    skipped = applied.skipped;
+  }
+
+  const checks = finalResults.map(({ id, label, ok, message, hint, fixable }) => ({ id, label, ok, message, hint, fixable }));
+  const ok = checks.every(c => c.ok);
+
+  if (format === 'json') {
+    out.write(JSON.stringify({ schemaVersion: 1, ok, checks, fixed, skipped }, null, 2) + '\n');
+    return { ok };
+  }
+
+  renderPlain(checks, { fixed, skipped, stream: out });
+  return { ok };
+}

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

@@ -48,6 +48,7 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('ticketlens')} ledger ${s.dim('[--format=json|csv]')}  Export your signed usage ledger  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} history ${s.dim('<TICKET-KEY>')}       Urgency timeline for a ticket  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} stats ${s.dim('[options]')}            Personal response-time metrics from local history`,
+    `    ${s.brand('ticketlens')} doctor ${s.dim('[--fix] [options]')}      Diagnose profile/license/connectivity/cache/queue problems`,
     `    ${s.brand('ticketlens')} note add ${s.dim('--title=... [--ticket=KEY]')}  Save a Recall note  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} note delete ${s.dim('--id=... [--ticket=KEY]')}  Remove a note from your local vault  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} recall ${s.dim('<query|TICKET-KEY>')}   Search your saved Recall notes  ${s.dim('[Pro]')}`,
@@ -1225,6 +1226,35 @@ export function printCollisionsHelp({ stream = process.stdout } = {}) {
   stream.write(lines.join('\n') + '\n');
 }
 
+export function printDoctorHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('doctor')} ${s.dim('[--fix] [--format=plain|json] [--profile=NAME]')}`,
+    '',
+    `  Diagnose common TicketLens problems: profile configuration, license`,
+    `  freshness, tracker connectivity, attachment cache health, and the Recall`,
+    `  sync queue. Free tier, fully unrestricted.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--fix')}              Attempt safe, non-destructive repairs for failing checks`,
+    `    ${s.brand('--format')}=${s.dim('plain')}    Human-readable output  ${s.dim('(default)')}`,
+    `    ${s.brand('--format')}=${s.dim('json')}     JSON output for scripting/piping`,
+    `    ${s.brand('--profile')}=${s.dim('NAME')}    Scope profile/connectivity/cache checks to one profile`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}         Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens doctor`,
+    `    ${s.dim('$')} ticketlens doctor --fix`,
+    `    ${s.dim('$')} ticketlens doctor --profile=work`,
+    `    ${s.dim('$')} ticketlens doctor --format=json`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
 export function printStatsHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [

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

@@ -14,7 +14,7 @@ export const LICENSE_TIERS = { free: 0, pro: 1, team: 2 };
 const LICENSE_FILE = 'license.json';
 const LICENSE_SECRET_FILE = 'license-hmac-secret.json';
 const REVALIDATION_DAYS = 7;   // attempt background revalidation after this many days
-const GRACE_DAYS = 30;          // treat license as invalid if not revalidated within this window
+export const GRACE_DAYS = 30;   // treat license as invalid if not revalidated within this window
 const MS_PER_DAY = 86400000;
 const upgradeUrl = () => `${siteBase()}/#pricing`;
 

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

@@ -21,6 +21,7 @@
 
 import readline from 'node:readline';
 import { DEFAULT_CONFIG_DIR, getVersion } from './config.mjs';
+import { runDoctor } from './doctor-command.mjs';
 import { runNoteAdd } from './note-command.mjs';
 import { runRecall } from './recall-command.mjs';
 import { runTicketComment, runTicketTransitionList, runTicketTransition, runTicketAssign, runTicketDuplicates, runTicketLinkList, runTicketLink, runTicketUpdate, runTicketCreate } from './ticket-command.mjs';
@@ -28,6 +29,17 @@ import { runTicketComment, runTicketTransitionList, runTicketTransition, runTick
 const PROTOCOL_VERSION = '2025-11-25';
 
 const TOOLS = [
+  {
+    name: 'doctor',
+    description: 'Diagnose common TicketLens problems: profile configuration, license freshness, tracker connectivity, attachment cache health, and the Recall sync queue. Always returns structured JSON. Free tier, fully unrestricted — including fix.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fix: { type: 'boolean', description: 'Attempt safe, non-destructive repairs for failing checks.' },
+        profile: { type: 'string', description: 'Scope profile/connectivity/cache checks to one profile.' },
+      },
+    },
+  },
   {
     name: 'recall_add',
     description: 'Save a Recall note — a gotcha, root cause, or non-obvious decision learned this session. Requires a TicketLens Pro license.',
@@ -167,6 +179,25 @@ function capturingStream() {
   };
 }
 
+function buildDoctorArgs({ fix, profile }) {
+  const args = ['--format=json'];
+  if (fix === true) args.push('--fix');
+  if (profile) args.push(`--profile=${profile}`);
+  return args;
+}
+
+async function callDoctor(args, { configDir, runDoctorFn }) {
+  const capture = capturingStream();
+  // runDoctor writes its final report to `out` (stdout by default) and only
+  // uses `stream` for --fix progress chatter — since this call always forces
+  // --format=json (see buildDoctorArgs), the report is what we need here.
+  // Both must be captured, not left to default: an uncaptured `out` would
+  // write the JSON report straight to this process's real stdout, which is
+  // the MCP JSON-RPC channel itself.
+  await runDoctorFn(buildDoctorArgs(args), { configDir, stream: capture, out: capture });
+  return { content: [{ type: 'text', text: capture.text }] };
+}
+
 /**
  * Builds runNoteAdd's cmdArgs array. Each `--flag=value` MUST stay a single,
  * discrete array element — runNoteAdd's parseFlag matches per-element via
@@ -370,6 +401,7 @@ async function callTicketCreate(args, { configDir, runTicketCreateFn }) {
 
 async function handleToolsCall(params, deps) {
   const { name, arguments: args = {} } = params ?? {};
+  if (name === 'doctor') return callDoctor(args, deps);
   if (name === 'recall_add') return callRecallAdd(args, deps);
   if (name === 'recall_search') return callRecallSearch(args, deps);
   if (name === 'ticket_comment') return callTicketComment(args, deps);
@@ -382,7 +414,7 @@ async function handleToolsCall(params, deps) {
   return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
 }
 
-async function handleMessage(raw, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn }) {
+async function handleMessage(raw, { configDir, runDoctorFn, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn }) {
   let msg;
   try {
     msg = JSON.parse(raw);
@@ -412,7 +444,7 @@ async function handleMessage(raw, { configDir, runNoteAddFn, runRecallFn, runTic
 
   if (method === 'tools/call') {
     try {
-      const result = await handleToolsCall(params, { configDir, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn });
+      const result = await handleToolsCall(params, { configDir, runDoctorFn, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn });
       return jsonRpcResult(id, result);
     } catch (err) {
       return jsonRpcError(id ?? null, -32603, `Internal error: ${err.message}`);
@@ -433,6 +465,7 @@ export function runMcpServer({
   configDir = DEFAULT_CONFIG_DIR,
   stdin = process.stdin,
   stdout = process.stdout,
+  runDoctorFn = runDoctor,
   runNoteAddFn = runNoteAdd,
   runRecallFn = runRecall,
   runTicketCommentFn = runTicketComment,
@@ -463,7 +496,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, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn });
+      const response = await handleMessage(line, { configDir, runDoctorFn, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn });
       if (response) stdout.write(response);
     }).catch(() => {});
   });

package/skills/jtb/scripts/lib/secret-scanner.mjs

@@ -13,7 +13,7 @@ const GIT_SHA_RE = /^[0-9a-f]{7,64}$/i;
 const TICKET_KEY_RE = /^[A-Z][A-Z0-9]+-\d+$/;
 const GIT_REFERENCE_WORD_RE = /\b(commit|sha\d*|revision|rev|digest|checksum|md5(sum)?|hash|fingerprint)\b/i;
 const HASH_LABEL_PREFIX_RE = /^[a-z0-9]+:/i;
-const EDGE_PUNCTUATION_RE = /^[`'"(),.]+|[`'"(),.]+$/g;
+const EDGE_PUNCTUATION_RE = /^[`'"(),.:]+|[`'"(),.:]+$/g;
 const MIN_RANDOM_TOKEN_LENGTH = 20;
 // Hex-alphabet strings (16 symbols) top out near 4.0 bits/char by definition, so a
 // threshold of 4.0 makes it nearly impossible to ever flag a hex-shaped secret.
@@ -37,6 +37,32 @@ const HARD_REJECT_PATTERNS = [
 
 const EMAIL_RE = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/;
 
+// A letters-only token ending in a recognized source-file extension reads as
+// high-entropy the same way a real secret does — a class name doubling as its
+// filename is the common case, but a deliberately-renamed or accidentally
+// letters-only secret (no digits, so the hard-reject patterns above don't
+// apply either) would match this shape too and MUST NOT be silently waved
+// through: security review confirmed a full-exemption version of this check
+// was a deterministic bypass (append ".php" to any 20+ char letters-only
+// secret and it passed clean). So this only ever downgrades a match to a
+// warning, never removes it from the reject reasons — see the two
+// independent checks against looksRandomCandidates in scanForSecrets below,
+// not a shortcut inside looksRandom itself. A bare identifier with no
+// extension (a method name, not a filename) isn't covered by this at all —
+// that shape is indistinguishable from a base64 secret fragment either way.
+const CODE_FILENAME_RE = /^[A-Za-z]+\.(php|m?js|tsx?|jsx|py|rb|java|go|rs|vue|s?css|md|json|ya?ml|sh)$/i;
+
+function looksLikeCodeFilename(rawToken) {
+  const stripped = stripEdgePunctuation(rawToken);
+  const match = stripped.match(CODE_FILENAME_RE);
+  // Requiring an internal case switch in the stem (the same signal used to
+  // detect base64 content elsewhere in this file) means a genuinely random
+  // single-case letter run plus a fake extension gets no special treatment
+  // at all — only tokens that already look like a real PascalCase/camelCase
+  // identifier reach the softer warning path below.
+  return match !== null && hasInternalCaseSwitch(match[0]);
+}
+
 function shannonEntropy(token) {
   const counts = new Map();
   for (const ch of token) counts.set(ch, (counts.get(ch) ?? 0) + 1);
@@ -183,8 +209,19 @@ export function scanForSecrets({ title = '', tags = [], body = '' } = {}) {
   const reasons = [];
   const warnings = [];
 
-  const tokens = combined.split(/\s+/).filter(Boolean);
-  const candidates = [...tokens, ...joinedChunkRuns(tokens)];
+  // Each field is tokenized on its own, and joinedChunkRuns runs separately
+  // per field, so a trailing tag word can never glue onto the next tag or
+  // onto the body's first word (see Trigger 3 in
+  // recall-secret-scanner-false-positives.md — tags echoing a phrase already
+  // repeated in the body were false-positiving via exactly this cross-field
+  // join). The hard-reject pass below intentionally keeps using the flat,
+  // cross-field `tokens`/`combined`/`despacedCombined`: those patterns match
+  // an exact literal prefix (AKIA, sk-, ghp_, eyJ, -----BEGIN), so joining
+  // across a field boundary can't turn them into a false positive the way
+  // entropy can.
+  const fieldTokenGroups = [title, ...tags, body].map(field => field.split(/\s+/).filter(Boolean));
+  const tokens = fieldTokenGroups.flat();
+  const candidates = [...tokens, ...fieldTokenGroups.flatMap(group => joinedChunkRuns(group))];
 
   // A known secret shape (AWS key, API key prefix, JWT, PEM block...) is recognized
   // by a specific literal prefix. Checked three ways, each catching what the
@@ -216,9 +253,20 @@ export function scanForSecrets({ title = '', tags = [], body = '' } = {}) {
   // only split secrets), an email joined with an adjacent word can produce a long
   // mixed string with incidentally high entropy. Emails get their own warning
   // below — they're not secrets, so they shouldn't feed the random-string check.
-  if (candidates.some(token => !EMAIL_RE.test(token) && looksRandom(token, combined))) {
+  //
+  // A code-filename-shaped candidate (looksLikeCodeFilename) is split out into
+  // its own warning instead of a reject reason: security review found that
+  // fully exempting this shape from the entropy check was a deterministic
+  // bypass (append ".php" to any letters-only secret and it passed clean).
+  // Downgrading to a warning — never silently dropping the signal — matches
+  // how an email address is already handled below.
+  const randomCandidates = candidates.filter(token => !EMAIL_RE.test(token) && looksRandom(token, combined));
+  if (randomCandidates.some(token => !looksLikeCodeFilename(token))) {
     reasons.push('Contains a long, random-looking string that could be a secret.');
   }
+  if (randomCandidates.some(token => looksLikeCodeFilename(token))) {
+    warnings.push('Contains a code-filename-shaped token that also reads as high-entropy — double-check it is not a credential.');
+  }
 
   if (EMAIL_RE.test(combined)) {
     warnings.push('Contains an email address.');