ticketlens 0.38.15 → 0.38.17

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.15",
+  "version": "0.38.17",
   "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/hooks/recall-nudge-lib.mjs

@@ -1,13 +1,15 @@
 /**
- * Shared helpers for the Recall nudge hooks (recall-nudge-post-tool.mjs,
- * recall-nudge-stop.mjs). Both read the same Claude Code hook stdin JSON
- * and the same session transcript — kept in one place so the detection
- * logic can't drift between the two hooks.
+ * Shared helpers for the Recall nudge Stop hook (recall-nudge-stop.mjs).
+ * The retired PostToolUse mid-session nudge (recall-nudge-post-tool.mjs)
+ * used to share this module too — removed because it only ever matched
+ * Bash tool calls and went silently inert once ticket work moved to MCP
+ * tools, which SKILL.md tells Claude to prefer over Bash whenever available.
  */
 
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import crypto from 'node:crypto';
 
 export const TICKET_KEY_RE = /\b[A-Z][A-Z0-9]{1,9}-\d+\b/;
 export const RECALL_FLAG_RE = /🔖\s*Recall-flag:/;
@@ -44,6 +46,59 @@ export function writeState(sessionId, state) {
   } catch { /* best-effort — a lost nudge counter is not worth failing the hook over */ }
 }
 
+// Two hours — how long a real capture in one directory counts as "recent
+// enough" to skip the Stop hook's nag, even from a brand-new session_id.
+export const CAPTURE_FRESHNESS_MS = 2 * 60 * 60 * 1000;
+
+/**
+ * Cross-session capture marker, keyed by a hash of `cwd` rather than
+ * `session_id`. The per-session_id state file (readState/writeState above)
+ * cannot answer "was something captured recently" once a compaction/resume
+ * event rolls the session_id over — that starts both a blank dedup state
+ * AND a blank transcript file, so a genuine earlier capture becomes
+ * invisible to scanTranscript(). This marker survives that boundary because
+ * it's keyed by the (stable) working directory instead.
+ *
+ * Lives in a user-private, mode-0700 subdirectory rather than directly in
+ * (often world-writable, on Linux) os.tmpdir() — unlike statePath()'s
+ * session_id (an unguessable UUID), a hash of `cwd` is derived from a much
+ * smaller, guessable input space (common project directory names), so a
+ * predictable path directly in shared tmp could be pre-planted by another
+ * local user on a shared box.
+ */
+function privateTmpDir() {
+  const owner = typeof process.getuid === 'function' ? process.getuid() : os.userInfo().username;
+  const dir = path.join(os.tmpdir(), `ticketlens-recall-nudge-${owner}`);
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  } catch { /* best-effort — a write into it below will just fail safely too */ }
+  return dir;
+}
+
+export function lastCapturePath(cwd) {
+  const hash = crypto.createHash('sha256').update(cwd || 'unknown').digest('hex').slice(0, 16);
+  return path.join(privateTmpDir(), `lastcapture-${hash}.json`);
+}
+
+export function readLastCaptureAt(cwd) {
+  try {
+    return JSON.parse(fs.readFileSync(lastCapturePath(cwd), 'utf8')).lastCaptureAt ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+export function writeLastCaptureAt(cwd, timestamp) {
+  try {
+    fs.writeFileSync(lastCapturePath(cwd), JSON.stringify({ lastCaptureAt: timestamp }));
+  } catch { /* best-effort — losing this marker only costs one extra nag next rollover */ }
+}
+
+export function hasRecentCapture(cwd, now = Date.now()) {
+  const lastCaptureAt = readLastCaptureAt(cwd);
+  return lastCaptureAt > 0 && (now - lastCaptureAt) < CAPTURE_FRESHNESS_MS;
+}
+
 /**
  * Reads the transcript (JSONL) and returns simple booleans about what
  * happened this session. Best-effort: any read/parse failure returns all

package/skills/jtb/hooks/recall-nudge-stop.mjs

@@ -10,25 +10,41 @@
  *      — the weaker "did anything ever get considered?" catch.
  * Anything else (no ticket work at all, or a note was already added) exits
  * clean — this must never be the reason a session can't end.
+ *
+ * The per-session_id "asked once" state (readState/writeState) cannot
+ * survive a compaction/resume event — that hands this hook a brand-new
+ * session_id, a blank dedup state, AND a blank transcript file, so a real
+ * earlier capture becomes invisible. The cross-session lastCapture marker
+ * (keyed by cwd, not session_id) is what actually bridges that boundary.
  */
 
-import { readStdinJson, readState, writeState, scanTranscript } from './recall-nudge-lib.mjs';
+import { readStdinJson, readState, writeState, scanTranscript, hasRecentCapture, writeLastCaptureAt } from './recall-nudge-lib.mjs';
 
 const input = readStdinJson();
 const sessionId = input?.session_id;
 const transcriptPath = input?.transcript_path;
+const cwd = input?.cwd ?? process.cwd();
 
 if (!sessionId || !transcriptPath) process.exit(0);
 
+const { sawTicketKey, sawRecallFlag, sawNoteAdd } = scanTranscript(transcriptPath);
+
+// Refreshed on every check, independent of the once-per-session gate below —
+// a capture that happens AFTER this session already nagged once must still
+// update the marker, or a later session_id rollover would find it stale.
+if (sawNoteAdd) writeLastCaptureAt(cwd, Date.now());
+
 const state = readState(sessionId);
 if (state.stopChecked) process.exit(0); // already asked once this session — respect the answer
 
-const { sawTicketKey, sawRecallFlag, sawNoteAdd } = scanTranscript(transcriptPath);
-
 if (!sawTicketKey || sawNoteAdd) {
   process.exit(0); // no ticket work, or already captured — nothing to force
 }
 
+if (hasRecentCapture(cwd)) {
+  process.exit(0); // a real capture landed recently in this same directory, just under a different session_id
+}
+
 state.stopChecked = true;
 writeState(sessionId, state);
 

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/hooks-setup.mjs

@@ -1,8 +1,12 @@
 /**
- * Installs the Recall nudge hooks (recall-nudge-post-tool.mjs,
- * recall-nudge-stop.mjs) into any detected Claude Code settings.json —
- * run from postinstall.mjs on every install/update so a user never has to
- * wire this by hand. Idempotent: safe to run on every `npm install`.
+ * Installs the Recall nudge Stop hook (recall-nudge-stop.mjs) into any
+ * detected Claude Code settings.json — run from postinstall.mjs on every
+ * install/update so a user never has to wire this by hand. Idempotent: safe
+ * to run on every `npm install`. Also cleans up the retired PostToolUse
+ * nudge (recall-nudge-post-tool.mjs) from any settings.json that still has
+ * it from a prior install — it only ever matched Bash tool calls, so it
+ * went silently inert once ticket work moved to MCP tools, and was removed
+ * rather than left as dead config.
  *
  * Never touches an existing settings.json's other content, and never
  * throws — a malformed or unreadable settings.json is skipped, not
@@ -16,12 +20,11 @@ import { homedir } from 'node:os';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const HOOKS_DIR = join(__dirname, '..', '..', 'hooks');
-const POST_TOOL_SCRIPT = join(HOOKS_DIR, 'recall-nudge-post-tool.mjs');
-const STOP_SCRIPT       = join(HOOKS_DIR, 'recall-nudge-stop.mjs');
+const STOP_SCRIPT = join(HOOKS_DIR, 'recall-nudge-stop.mjs');
 
-// Distinctive substring used to find/replace our own entries on re-install —
+// Distinctive substrings used to find our own entries on re-install/cleanup —
 // never matches anything a user could plausibly have written by hand.
-const MARKER = 'recall-nudge-post-tool.mjs';
+const RETIRED_POST_TOOL_MARKER = 'recall-nudge-post-tool.mjs';
 const STOP_MARKER = 'recall-nudge-stop.mjs';
 
 const CLAUDE_DIRS = [
@@ -42,6 +45,11 @@ function makeHookEntry(scriptPath, matcher) {
   };
 }
 
+// Both functions below locate our own hook by a marker substring inside a
+// list entry's `hooks` array, but must never drop an unrelated hook a user
+// happens to have colocated in that same array entry (e.g. sharing our
+// matcher) — only our own matching inner hook is ever added/replaced/removed.
+
 function upsertHookEntry(list, marker, entry) {
   const idx = list.findIndex(h =>
     (h.hooks || []).some(inner => typeof inner.command === 'string' && inner.command.includes(marker)),
@@ -50,12 +58,32 @@ function upsertHookEntry(list, marker, entry) {
     list.push(entry);
     return 'added';
   }
-  if (JSON.stringify(list[idx]) === JSON.stringify(entry)) return 'unchanged';
-  list[idx] = entry;
+  const ownInner = entry.hooks[0]; // makeHookEntry always builds a single-command entry
+  const otherHooks = list[idx].hooks.filter(inner => !(typeof inner.command === 'string' && inner.command.includes(marker)));
+  // Our hook was the only thing in this entry — safe to fully replace
+  // (also picks up a matcher change, if any). Otherwise preserve the
+  // entry's existing matcher and other hooks, just swap our own inner hook.
+  const merged = otherHooks.length === 0 ? entry : { ...list[idx], hooks: [...otherHooks, ownInner] };
+  if (JSON.stringify(list[idx]) === JSON.stringify(merged)) return 'unchanged';
+  list[idx] = merged;
   return 'updated';
 }
 
-function installInto(settingsPath) {
+function removeHookEntry(list, marker) {
+  const idx = list.findIndex(h =>
+    (h.hooks || []).some(inner => typeof inner.command === 'string' && inner.command.includes(marker)),
+  );
+  if (idx === -1) return 'absent';
+  const remaining = list[idx].hooks.filter(inner => !(typeof inner.command === 'string' && inner.command.includes(marker)));
+  if (remaining.length === 0) {
+    list.splice(idx, 1);
+  } else {
+    list[idx] = { ...list[idx], hooks: remaining };
+  }
+  return 'removed';
+}
+
+export function installInto(settingsPath) {
   let settings = {};
   if (existsSync(settingsPath)) {
     try {
@@ -69,18 +97,14 @@ function installInto(settingsPath) {
   settings.hooks.PostToolUse ??= [];
   settings.hooks.Stop ??= [];
 
-  const postResult = upsertHookEntry(
-    settings.hooks.PostToolUse,
-    MARKER,
-    makeHookEntry(POST_TOOL_SCRIPT, 'Bash'),
-  );
+  const postCleanupResult = removeHookEntry(settings.hooks.PostToolUse, RETIRED_POST_TOOL_MARKER);
   const stopResult = upsertHookEntry(
     settings.hooks.Stop,
     STOP_MARKER,
     makeHookEntry(STOP_SCRIPT, '*'),
   );
 
-  if (postResult === 'unchanged' && stopResult === 'unchanged') {
+  if (postCleanupResult === 'absent' && stopResult === 'unchanged') {
     return { status: 'unchanged' };
   }
 
@@ -89,7 +113,7 @@ function installInto(settingsPath) {
   // Atomic on POSIX — avoids ever leaving settings.json half-written.
   renameSync(tmpPath, settingsPath);
 
-  return { status: 'installed', postResult, stopResult };
+  return { status: 'installed', postCleanupResult, stopResult };
 }
 
 /**

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/profile-resolver.mjs

@@ -262,6 +262,22 @@ export function resolveProfile(ticketKey, opts = {}) {
   return null;
 }
 
+/**
+ * Names of every profile whose ticketPrefixes includes `prefix` — used to
+ * cross-check a resolved connection against the project/team key the caller
+ * actually asked for. `ticket_create` has no ticket key to prefix-match
+ * against (unlike every other ticket-write command), so this checks the raw
+ * project/team key directly instead, as a safety net against silently
+ * creating a ticket on the wrong tracker.
+ */
+export function findProfilesByPrefix(prefix, configDir = DEFAULT_CONFIG_DIR) {
+  const config = loadProfiles(configDir);
+  if (!config) return [];
+  return Object.entries(config.profiles)
+    .filter(([, profile]) => profile.ticketPrefixes?.includes(prefix))
+    .map(([name]) => name);
+}
+
 export function resolveConnection(ticketKey, opts = {}) {
   const { env = process.env, configDir = DEFAULT_CONFIG_DIR, profileName, onWarning, onProfileNotFound, cwd } = opts;
 

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

@@ -12,7 +12,7 @@
 import os from 'node:os';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { isLicensed, showUpgradePrompt } from './license.mjs';
-import { resolveConnection } from './profile-resolver.mjs';
+import { resolveConnection, findProfilesByPrefix } from './profile-resolver.mjs';
 import { resolveAdapter } from './resolve-adapter.mjs';
 import { checkCooldown, recordAction } from './ticket-action-cooldown.mjs';
 import { logAction } from './ticket-action-log.mjs';
@@ -218,15 +218,24 @@ function requireTicketKey(cmdArgs, usage, stream) {
 
 /**
  * `ticketKey` is undefined for ticket_create — there is no existing ticket to
- * prefix-match a connection from, so resolution falls through to --profile
- * or the default profile (resolveConnectionFn already handles a falsy
- * ticketKey by skipping prefix matching, see profile-resolver.mjs).
+ * prefix-match a connection from, so resolution falls through to --profile,
+ * the folder-based `cwd` match, or the default profile (resolveConnectionFn
+ * already handles a falsy ticketKey by skipping prefix matching, see
+ * profile-resolver.mjs). `cwd` is always the running process's own — every
+ * ticket-write command runs synchronously within a single CLI/MCP-server
+ * invocation, so there is never a separate "caller's cwd" to thread through.
+ *
+ * Returns `{ adapter, conn }` (not just the adapter) so callers that need to
+ * cross-check the resolved connection's identity — currently only
+ * `runTicketCreate`'s profile/project mismatch safety net — have it without
+ * re-resolving.
  */
 function resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream }) {
   const profileName = parseFlag(cmdArgs, 'profile');
   const conn = resolveConnectionFn(ticketKey, {
     configDir,
     profileName,
+    cwd: process.cwd(),
     onWarning: (msg) => stream.write(`  ⚠ ${msg}\n`),
   });
   if (!conn.baseUrl) {
@@ -235,7 +244,7 @@ function resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnection
       : `  No connection configured. Run \`ticketlens init\` or pass --profile=NAME.\n`);
     return null;
   }
-  return resolveAdapterFn(conn);
+  return { adapter: resolveAdapterFn(conn), conn };
 }
 
 /**
@@ -272,8 +281,9 @@ export async function runTicketComment(cmdArgs, {
     return { ok: false };
   }
 
-  const adapter = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
-  if (!adapter) return { ok: false };
+  const resolved = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!resolved) return { ok: false };
+  const { adapter } = resolved;
   const s = createStyler({ isTTY: stream.isTTY });
 
   // Uploaded BEFORE the comment write so a tracker capable of inline
@@ -330,8 +340,9 @@ export async function runTicketTransitionList(cmdArgs, {
   const ticketKey = requireTicketKey(cmdArgs, usage, stream);
   if (!ticketKey) return { ok: false };
 
-  const adapter = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
-  if (!adapter) return { ok: false };
+  const resolved = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!resolved) return { ok: false };
+  const { adapter } = resolved;
 
   try {
     const options = await adapter.getTransitions(ticketKey);
@@ -396,8 +407,9 @@ export async function runTicketTransition(cmdArgs, {
     return { ok: false };
   }
 
-  const adapter = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
-  if (!adapter) return { ok: false };
+  const resolved = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!resolved) return { ok: false };
+  const { adapter } = resolved;
 
   try {
     const result = await adapter.transition(ticketKey, target);
@@ -456,8 +468,9 @@ export async function runTicketAssign(cmdArgs, {
     return { ok: false };
   }
 
-  const adapter = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
-  if (!adapter) return { ok: false };
+  const resolved = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!resolved) return { ok: false };
+  const { adapter } = resolved;
 
   try {
     const result = await adapter.assignToSelf(ticketKey);
@@ -502,8 +515,9 @@ export async function runTicketDuplicates(cmdArgs, {
     }
   }
 
-  const adapter = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
-  if (!adapter) return { ok: false };
+  const resolved = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!resolved) return { ok: false };
+  const { adapter } = resolved;
 
   try {
     // depth: 0 — only the shallow linkedIssues list is needed (for explicit
@@ -581,8 +595,9 @@ export async function runTicketLinkList(cmdArgs, {
   const targetKey = requireTicketKey(cmdArgs.slice(1), usage, stream);
   if (!targetKey) return { ok: false };
 
-  const adapter = resolveTicketAdapter(sourceKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
-  if (!adapter) return { ok: false };
+  const resolved = resolveTicketAdapter(sourceKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!resolved) return { ok: false };
+  const { adapter } = resolved;
 
   try {
     const types = await adapter.getLinkTypes();
@@ -658,8 +673,9 @@ export async function runTicketLink(cmdArgs, {
     return { ok: false };
   }
 
-  const adapter = resolveTicketAdapter(sourceKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
-  if (!adapter) return { ok: false };
+  const resolved = resolveTicketAdapter(sourceKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!resolved) return { ok: false };
+  const { adapter } = resolved;
 
   if (adapter.type === 'github' && type.toLowerCase() !== 'duplicate') {
     stream.write(`  GitHub only supports linking as a duplicate — no generic link types. Got type "${type}".\n`);
@@ -748,8 +764,9 @@ export async function runTicketUpdate(cmdArgs, {
     return { ok: false };
   }
 
-  const adapter = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
-  if (!adapter) return { ok: false };
+  const resolved = resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!resolved) return { ok: false };
+  const { adapter } = resolved;
 
   if (adapter.type === 'github' && priority !== undefined) {
     stream.write(`  GitHub Issues have no native priority field — cannot update priority on ${ticketKey}. Remove --priority and retry.\n`);
@@ -808,6 +825,7 @@ export async function runTicketCreate(cmdArgs, {
   logActionFn = logAction,
   readMetadataCacheFn = readMetadataCache,
   writeMetadataCacheFn = writeMetadataCache,
+  findProfilesByPrefixFn = findProfilesByPrefix,
   actor = os.userInfo().username,
 } = {}) {
   const usage = 'Usage: ticketlens create --project=KEY --type="Task" --summary="..." [--description="..."] [--profile=NAME]\n';
@@ -824,8 +842,9 @@ export async function runTicketCreate(cmdArgs, {
   const description = parseFlag(cmdArgs, 'description');
   const attachPaths = parseAttachPaths(cmdArgs);
 
-  const adapter = resolveTicketAdapter(undefined, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
-  if (!adapter) return { ok: false };
+  const resolved = resolveTicketAdapter(undefined, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!resolved) return { ok: false };
+  const { adapter, conn } = resolved;
   const s = createStyler({ isTTY: stream.isTTY });
   const attachRefused = refuseGithubAttachments(adapter, attachPaths, stream);
 
@@ -841,6 +860,28 @@ export async function runTicketCreate(cmdArgs, {
     stream.write(`  Note: --type is ignored by ${adapter.type} — issue created without it.\n`);
   }
 
+  // Highest-blast-radius write in the family: no ticket key exists yet to
+  // prefix-match against, so a resolution that quietly lands on the wrong
+  // profile (e.g. an unconfigured cwd falling to the default) fabricates a
+  // real ticket on the wrong tracker before anyone notices. Only refuses
+  // when a DIFFERENT profile is a known, better owner of this exact project
+  // key — a genuinely new, not-yet-registered project proceeds untouched.
+  // Skipped when the caller explicitly passed --profile=NAME: that is
+  // deliberate, informed intent (the same trust resolveProfile() itself
+  // already gives an explicit flag over every other signal), and this guard
+  // must never be a dead end with no way to force a legitimate create through.
+  if (adapter.type !== 'github' && project && conn.profileName && !parseFlag(cmdArgs, 'profile')) {
+    const owningProfiles = findProfilesByPrefixFn(project, configDir);
+    if (owningProfiles.length > 0 && !owningProfiles.includes(conn.profileName)) {
+      stream.write(
+        `  Project "${project}" is registered under profile "${owningProfiles[0]}", not the resolved profile ` +
+        `"${conn.profileName}". Pass --profile=${owningProfiles[0]} to target the right tracker, or ` +
+        `--profile=${conn.profileName} to confirm this is intentional.\n`,
+      );
+      return { ok: false };
+    }
+  }
+
   // JSON-encoded, not naively colon-joined — project/type/summary are free
   // text that can themselves contain ":", which would let two genuinely
   // different tuples collide onto the same cooldown key.

package/skills/jtb/hooks/recall-nudge-post-tool.mjs

@@ -1,52 +0,0 @@
-#!/usr/bin/env node
-/**
- * PostToolUse hook (matcher: Bash) — mid-session Recall nudge.
- *
- * Non-blocking by design: this only prints an advisory reminder to stdout
- * every NUDGE_EVERY ticket-related Bash calls, and only if Claude hasn't
- * self-flagged a Recall-worthy insight (🔖 Recall-flag:) since the last one.
- * Never exits non-zero — a mid-session nudge must never interrupt real work.
- */
-
-import { readStdinJson, statePath, readState, writeState, TICKET_KEY_RE, scanTranscript } from './recall-nudge-lib.mjs';
-
-const NUDGE_EVERY = 8; // ticket-related Bash calls between nudges
-
-const input = readStdinJson();
-const command = input?.tool_input?.command ?? '';
-const sessionId = input?.session_id;
-const transcriptPath = input?.transcript_path;
-
-if (!TICKET_KEY_RE.test(command) || !sessionId) {
-  process.exit(0);
-}
-
-const state = readState(sessionId);
-state.ticketToolCalls = (state.ticketToolCalls ?? 0) + 1;
-
-// If Claude already self-flagged since we last reset, don't nag — reset the
-// counter so the next nudge only fires after another full quiet stretch.
-if (transcriptPath) {
-  const { sawRecallFlag } = scanTranscript(transcriptPath);
-  if (sawRecallFlag) {
-    state.ticketToolCalls = 0;
-    writeState(sessionId, state);
-    process.exit(0);
-  }
-}
-
-if (state.ticketToolCalls >= NUDGE_EVERY) {
-  state.ticketToolCalls = 0;
-  state.lastNudgeAt = Date.now();
-  writeState(sessionId, state);
-  process.stdout.write(
-    'Reminder (not a request for action right now): if something non-obvious was ' +
-    'confirmed in the last stretch of ticket work — a gotcha, a root cause, a ' +
-    'decision with non-obvious rationale — capture it now via `ticketlens note add` ' +
-    'per the jtb skill\'s Recall guidance, then keep going.\n',
-  );
-  process.exit(0);
-}
-
-writeState(sessionId, state);
-process.exit(0);