ticketlens 0.38.30 → 0.38.32

package/README.md

@@ -453,7 +453,7 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 **Removing a note:** `ticketlens note delete --id="..." [--ticket=KEY]` removes a note from your local vault. Local only — if it was already pushed to a team, teammates who pulled it keep their copy; deleting it there too is a manager action from the Console (Admin > Recall).
 
-**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `recall_add`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, `ticket_link`, `ticket_update`, and `ticket_create` as native tools — any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same Pro gate, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
+**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `fetch`, `triage`, `compliance`, `review`, `standup`, `pr`, `doctor`, `recall_add`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, `ticket_link`, `ticket_update`, and `ticket_create` as native tools — any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same license gate per tool, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. `fetch`, `doctor`, and `standup` are Free; `triage`'s base scan is Free with some options gated Pro/Team, same as the CLI (`ticketlens triage --help`); `compliance` and `pr` are Free, sharing a 3-checks/month cap on their requirements-coverage section, Pro unlimited; `review` is Free for branch/files/ticket context, with its coverage/focus section requiring Pro as a plain license check — it does not draw from that same monthly counter; every other tool needs Pro. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
 
 `note add`'s save confirmation and `recall`'s search results are styled by default in a terminal; add `--plain` to either for bare, pipe-safe output. `recall` always shows each note's file ID (e.g. `[1784135399545-fe01c4.md]`) so you can open it directly (`cat ~/.ticketlens/recall/<PREFIX>/<id>`), or pass `--full` to print the full body content inline instead. Each result shows a relative time (`2h ago`, `3d ago`) rather than a bare date — the full-precision timestamp is always in the note file's own frontmatter.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.38.30",
+  "version": "0.38.32",
   "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.34.1 -->
+<!-- jtb-skill-version: 0.37.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.
@@ -106,6 +106,8 @@ Where `$EXTRA_ARGS` are any flags passed (e.g. `--stale=3 --status=QA --profile=
 
 **IMPORTANT:** Copy the script's stdout and display it directly as your response text (not inside a tool result). This ensures the markdown table renders visibly and URLs are clickable in the terminal. No VCS enrichment, no plan mode. Stop here.
 
+If this harness has TicketLens's MCP server configured (a tool named `triage` — often shown as `mcp__ticketlens__triage` — visible in your tool list), prefer it over the bash form: same license gate per option (Free base scan, Pro `save`/`all`/`digest`, Team `assignee`/`sprint`/`export`/`project`/`label`/`priority`) — just no shell command to construct. It accepts `profile`/`stale`/`status`/`sort` plus those gated options; `--push`/`--share` aren't exposed yet — fall back to the bash form for those.
+
 ---
 
 ### Collisions subcommand
@@ -125,6 +127,63 @@ Display the script's stdout directly. No plan mode. Stop here.
 
 ---
 
+### Standup subcommand
+
+If the first argument is `standup`:
+
+Run:
+```bash
+ticketlens standup $EXTRA_ARGS
+```
+
+Where `$EXTRA_ARGS` are any flags passed (e.g. `--since=48 --format=pr --profile=acme`).
+
+Summarizes recent git commits grouped by linked ticket key. `--since=N` (hours, default 24) or a git-compatible date expression (`--since="3 days ago"`); `--format=standup` (default) renders a per-ticket standup update, `--format=pr` renders the same grouped commits as PR-body-style markdown. Read-only, fully free tier — no license gate on any option.
+
+Display the script's stdout directly. No plan mode. Stop here.
+
+If this harness has TicketLens's MCP server configured (a tool named `standup` — often shown as `mcp__ticketlens__standup` — visible in your tool list), prefer it over the bash form: same output, no license gate, no shell command to construct. It accepts `since`/`format`/`profile`.
+
+---
+
+### PR subcommand
+
+If the first argument is `pr`:
+
+Run:
+```bash
+ticketlens pr PROJ-123 $EXTRA_ARGS
+```
+
+Where `$EXTRA_ARGS` are any flags passed (e.g. `--profile=acme`). Requires a ticket key as the first positional argument.
+
+Assembles a ready-to-paste PR description: what changed (from commits linked to the ticket), linked tickets, and — if the ticket has acceptance criteria — a requirements-coverage section. Read-only. The requirements-coverage section reuses the same Free-tier 3-checks/month counter as `--compliance`/`ticketlens compliance` — running `pr` on a ticket with acceptance criteria counts against that shared monthly limit; Pro removes the cap.
+
+Display the script's stdout directly. No plan mode. Stop here.
+
+If this harness has TicketLens's MCP server configured (a tool named `pr` — often shown as `mcp__ticketlens__pr` — visible in your tool list), prefer it over the bash form: same output, same shared compliance-counter caveat, no shell command to construct. It accepts `ticket`/`profile`.
+
+---
+
+### Review subcommand
+
+If the first argument is `review`:
+
+Run:
+```bash
+ticketlens review $EXTRA_ARGS
+```
+
+Where `$EXTRA_ARGS` are any flags passed (e.g. `--base=develop --profile=acme`). No required positional argument — operates on the current branch.
+
+Assembles PR review context from the current git branch: changed files, linked-ticket summaries from commits/branch name, and (Pro) a requirements-coverage / review-focus section extracted from the diff against acceptance criteria. `--base=BRANCH` (or its alias `--branch=BRANCH`) sets the diff base, auto-detecting `main`/`master`/`develop` when omitted. Read-only — never modifies the tracker or the repo. Free tier gets branch info, changed files, and ticket context; Pro adds the requirements-coverage and review-focus sections — same split as `--compliance`.
+
+Display the script's stdout directly. No plan mode. Stop here.
+
+If this harness has TicketLens's MCP server configured (a tool named `review` — often shown as `mcp__ticketlens__review` — visible in your tool list), prefer it over the bash form: same tier gate (Free: branch/files/tickets, Pro: +coverage/focus), no shell command to construct. It accepts `base`/`branch`/`profile` — `base` and `branch` are aliases; if both are given, `base` wins.
+
+---
+
 ### Fetch ticket workflow (default)
 
 ### Step 1: Validate environment
@@ -145,6 +204,8 @@ Where `$TICKET_KEY` is the first argument (e.g. `PROD-1234`) and `$EXTRA_ARGS` a
 
 The script outputs a structured markdown TicketBrief to stdout. If it fails (exit code 1), show the stderr message to the user.
 
+If this harness has TicketLens's MCP server configured (a tool named `fetch` — often shown as `mcp__ticketlens__fetch` — visible in your tool list), prefer it over the bash form: same license gate (Free), same cache — just no shell command to construct or stdout to parse. It accepts `ticket`/`profile`/`depth`, matching `$TICKET_KEY`/`--profile`/`--depth` above; other CLI flags (`--summarize`, `--handoff`, `--no-cache`, etc.) aren't exposed yet — fall back to the bash form for those.
+
 ### Step 2b: Read attached files
 
 Check if the TicketBrief contains an `## Attachments` section. If it does, for each line containing a backtick-quoted absolute path, call the Read tool on that path based on file type:
@@ -400,6 +461,11 @@ Use this evaluation order:
 ### Privacy
 `--compliance` never sends data anywhere. The diff stays local. All analysis is performed by Claude Code within your session context.
 
+### Standalone command
+The same tier-gated check also runs as its own command — `ticketlens compliance PROJ-123` — independent of a full ticket fetch. This is what `ticketlens install-hooks` wires into a pre-push git hook (`ticketlens compliance "$KEY" || exit 1`, gated on a configurable coverage threshold). It shares the same `FREE_LIMIT`/Pro gate and the same compliance ledger as the `--compliance` flag above.
+
+If this harness has TicketLens's MCP server configured (a tool named `compliance` — often shown as `mcp__ticketlens__compliance` — visible in your tool list), prefer it over the bash form: same tier gate (Free: 3 checks/month, Pro: unlimited), same report — just no shell command to construct or stdout to parse. It accepts `ticket`/`profile`, matching the standalone command's arguments above.
+
 ---
 
 ## Advanced Options

package/skills/jtb/scripts/fetch-my-tickets.mjs

@@ -57,6 +57,12 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     env = envOrOpts;
   }
 
+  // Injectable stderr-equivalent — defaults to the real stream so every existing
+  // CLI caller (which never sets opts.stream) is byte-identical to before. Lets
+  // a long-lived host (the MCP server) capture banners/errors instead of losing
+  // them to a real process.stderr it never reads.
+  const stream = opts.stream ?? process.stderr;
+
   // Strip leading 'triage' subcommand if present (when called via CLI router)
   if (args[0] === 'triage') args = args.slice(1);
 
@@ -99,7 +105,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   const saveArg = args.find(a => a.startsWith('--save='))?.split('=').slice(1).join('=') ?? null;
 
   if (exportArg && exportArg !== 'csv' && exportArg !== 'json') {
-    process.stderr.write(`Error: --export must be csv or json, got: ${exportArg}\n`);
+    stream.write(`Error: --export must be csv or json, got: ${exportArg}\n`);
     process.exitCode = 1;
     return;
   }
@@ -120,14 +126,14 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   // --save=FILE: Pro gate + validate path is not a directory
   if (saveArg) {
     if (!licensedFn('pro', configDir)) {
-      upgradeFn('pro', '--save');
+      upgradeFn('pro', '--save', { stream });
       process.exitCode = 1;
       return;
     }
     const resolvedSave = resolvePath(saveArg);
     try {
       if (statSync(resolvedSave).isDirectory()) {
-        process.stderr.write(`Error: --save path must be a file, not a directory: ${resolvedSave}\n`);
+        stream.write(`Error: --save path must be a file, not a directory: ${resolvedSave}\n`);
         process.exitCode = 1;
         return;
       }
@@ -138,7 +144,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   if (projectArg || labelArg || priorityArg) {
     if (!licensedFn('team', configDir)) {
       const flag = projectArg ? '--project' : labelArg ? '--label' : '--priority';
-      upgradeFn('team', flag);
+      upgradeFn('team', flag, { stream });
       process.exitCode = 1;
       return;
     }
@@ -147,14 +153,14 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   // --all: triage all configured profiles in parallel with live status block
   if (allFlag) {
     if (!licensedFn('pro', configDir)) {
-      upgradeFn('pro', '--all');
+      upgradeFn('pro', '--all', { stream });
       process.exitCode = 1;
       return;
     }
     const profilesConfig = loadProfiles(configDir);
     const profileNames = profilesConfig?.profiles ? Object.keys(profilesConfig.profiles) : [];
     if (profileNames.length === 0) {
-      process.stderr.write('Error: No profiles configured. Run `ticketlens init` first.\n');
+      stream.write('Error: No profiles configured. Run `ticketlens init` first.\n');
       process.exitCode = 1;
       return;
     }
@@ -234,14 +240,14 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
 
   // Team-tier gate: --assignee and --sprint require a Team license
   if ((assigneeArg || sprintArg) && !licensedFn('team', configDir)) {
-    upgradeFn('team', assigneeArg ? '--assignee' : '--sprint');
+    upgradeFn('team', assigneeArg ? '--assignee' : '--sprint', { stream });
     process.exitCode = 1;
     return;
   }
 
   // Team-tier gate: --export requires a Team license
   if (exportArg && !licensedFn('team', configDir)) {
-    upgradeFn('team', '--export');
+    upgradeFn('team', '--export', { stream });
     process.exitCode = 1;
     return;
   }
@@ -256,14 +262,14 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     configDir,
     profileName,
     cwd,
-    onWarning: (w) => process.stderr.write(w + '\n'),
+    onWarning: (w) => stream.write(w + '\n'),
     onProfileNotFound: (info) => { profileError = info; },
   });
 
   const hasAuth = conn.pat || (conn.email && conn.apiToken);
   if (!conn.baseUrl || !hasAuth) {
     if (profileError) {
-      const picked = await promptProfileSelect(profileError);
+      const picked = await promptProfileSelect(profileError, { stream });
       if (picked) {
         // Re-run with the selected profile
         const newArgs = args.filter(a => !a.startsWith('--profile='));
@@ -275,7 +281,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       const msg = noProfiles
         ? 'Error: Could not determine Jira profile.\nRun `ticketlens init` to set up your connection.'
         : 'Error: Could not determine Jira profile. Use --profile=NAME or add projectPaths to ~/.ticketlens/profiles.json';
-      process.stderr.write(msg + '\n');
+      stream.write(msg + '\n');
     }
     process.exitCode = 1;
     return;
@@ -304,7 +310,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   const priorityClause = priorityArg  ? ` AND priority = "${escapeJql(priorityArg.split('=')[1])}"` : '';
   const jql = `${assigneeClause} AND status IN (${statusList})${sprintClause}${projectClause}${labelClause}${priorityClause} ORDER BY updated DESC`;
 
-  const session = createSession(conn);
+  const session = createSession(conn, { stream });
   session.spin(`Connecting to ${session.label}…`);
 
   // Fire both requests concurrently — they are independent of each other
@@ -329,7 +335,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   }
 
   session.connected();
-  process.stderr.write('\n');
+  stream.write('\n');
 
   const scanSpinner = createSpinner('Scanning tickets…');
   scanSpinner.start();
@@ -341,7 +347,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     scanSpinner.stop();
     if (err.status === 400 && err.detail && /does not exist for the field 'status'/.test(err.detail)) {
       const s = session.styler;
-      const out = process.stderr;
+      const out = stream;
       out.write(`\n  ${s.yellow('○')} Status mismatch — checking Jira...\n`);
       try {
         const available = await adapter.fetchStatuses();
@@ -424,7 +430,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     : currentUser;
 
   if (assigneeName) {
-    process.stderr.write(`Viewing ${assigneeName}'s tickets\n\n`);
+    stream.write(`Viewing ${assigneeName}'s tickets\n\n`);
   }
 
   const scored = tickets.map(t => scoreAttention(t, effectiveUser, { staleDays, customRules: conn.attentionRules, staleRule: conn.staleRule ?? null }));
@@ -445,7 +451,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   // --digest: POST scored results to the digest backend endpoint
   if (digestFlag) {
     if (!licensedFn('pro', configDir)) {
-      upgradeFn('pro', '--digest');
+      upgradeFn('pro', '--digest', { stream });
       process.exitCode = 1;
       return;
     }

package/skills/jtb/scripts/fetch-ticket.mjs

@@ -336,17 +336,20 @@ async function countRecallInjection(recallNotes, configDir, opts) {
   }
 }
 
-function makeSpinner(s) {
-  // setInterval won't fire while spawnSync blocks the event loop, so we draw
-  // synchronously on update() and only use setInterval during async fetch phases.
-  if (!process.stderr.isTTY) return { update: () => {}, startAnim: () => {}, done: () => {} };
+// setInterval won't fire while spawnSync blocks the event loop, so we draw
+// synchronously on update() and only use setInterval during async fetch phases.
+// Both callers pass run()'s errStream, so the spinner shares the same isTTY and
+// write target as everything else the command emits: the real process.stderr for
+// a CLI user, the captured printErr under MCP (where the draws must not leak).
+function makeSpinner(s, { isTTY, write }) {
+  if (!isTTY) return { update: () => {}, startAnim: () => {}, done: () => {} };
   const frames = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
   let fi = 0, msg = '', lastW = 0, timerId = null, finished = false;
 
   const draw = () => {
     const raw = `  ${s.brand(frames[fi % frames.length])} ${s.dim(msg)}`;
     const vis = raw.replace(/\x1b\[[0-9;]*m/g, '');
-    process.stderr.write(`\r${raw}${' '.repeat(Math.max(0, lastW - vis.length))}`);
+    write(`\r${raw}${' '.repeat(Math.max(0, lastW - vis.length))}`);
     lastW = vis.length;
   };
 
@@ -360,7 +363,7 @@ function makeSpinner(s) {
       if (finished) return;
       finished = true;
       if (timerId) { clearInterval(timerId); timerId = null; }
-      process.stderr.write('\r\x1b[2K');
+      write('\r\x1b[2K');
     },
   };
 }
@@ -472,9 +475,9 @@ const RETRY_OPTIONS = [
 ];
 
 export async function run(args, envOrOpts = process.env, fetcher = globalThis.fetch, configDir = undefined) {
-  // Support opts-object injection: run(args, { env, fetcher, configDir, detectVcs, getDiff, print })
+  // Support opts-object injection: run(args, { env, fetcher, configDir, detectVcs, getDiff, print, printErr })
   let env, opts;
-  if (envOrOpts && typeof envOrOpts === 'object' && !Array.isArray(envOrOpts) && ('env' in envOrOpts || 'fetcher' in envOrOpts || 'print' in envOrOpts || 'detectVcs' in envOrOpts || 'getDiff' in envOrOpts)) {
+  if (envOrOpts && typeof envOrOpts === 'object' && !Array.isArray(envOrOpts) && ('env' in envOrOpts || 'fetcher' in envOrOpts || 'print' in envOrOpts || 'printErr' in envOrOpts || 'detectVcs' in envOrOpts || 'getDiff' in envOrOpts)) {
     opts = envOrOpts;
     env = opts.env ?? process.env;
     fetcher = opts.fetcher ?? globalThis.fetch;
@@ -485,6 +488,27 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   }
 
   const printFn = opts.print ?? ((chunk) => process.stdout.write(chunk));
+  // Mirrors printFn above — the bare ticket-fetch, compliance, pr, review, and standup
+  // paths all use this now (each has an MCP tool). `ledger` above still writes directly
+  // to the real process.stderr (no MCP tool yet); `install-hooks` is CLI-only and never
+  // gets one.
+  const printErrFn = opts.printErr ?? ((chunk) => process.stderr.write(chunk));
+  // Reused on every recursive self-call in the bare-fetch path (profile-prompt retries)
+  // so an injected print/printErr survives the retry instead of silently reverting to
+  // the real stdout/stderr.
+  const selfOpts = { env, fetcher, configDir, print: printFn, printErr: printErrFn };
+  // Passed to every stream-shaped helper (createSession, the profile-prompt pickers,
+  // handleUnknownFlags) in the bare-fetch path below. isTTY MUST reflect the real
+  // process.stderr.isTTY, not a hardcoded false: these helpers use it to decide
+  // whether to render an animated/interactive UI at all, for real CLI users too, not
+  // just MCP calls. Their own separate `!process.stdin.setRawMode` gate — always true
+  // under the MCP server, since its stdin is the JSON-RPC channel, never a TTY — is
+  // what actually keeps the interactive branch from firing under MCP; isTTY here only
+  // controls real-terminal UX and must stay accurate for that to keep working. Injectable
+  // via opts.isTTY so a test can assert deterministic behavior without mutating the real,
+  // process-global process.stderr.isTTY (unsafe to flip mid-suite — see fetch-ticket.test.mjs).
+  const isTTY = opts.isTTY ?? process.stderr.isTTY;
+  const errStream = { write: printErrFn, isTTY };
 
   if (args.includes('--help') || args.includes('-h')) {
     printFetchHelp();
@@ -528,12 +552,12 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     const { assemblePr } = await import('./lib/pr-assembler.mjs');
     const ticketKeyArg = args[1];
     if (!ticketKeyArg) {
-      process.stderr.write('Error: "pr" requires a ticket key. Usage: ticketlens pr PROJ-123\n');
+      printErrFn('Error: "pr" requires a ticket key. Usage: ticketlens pr PROJ-123\n');
       process.exitCode = 1;
       return;
     }
     if (!TICKET_KEY_PATTERN.test(ticketKeyArg)) {
-      process.stderr.write(`Error: "${ticketKeyArg}" is not a valid ticket key. Expected format: PROJ-123\n`);
+      printErrFn(`Error: "${ticketKeyArg}" is not a valid ticket key. Expected format: PROJ-123\n`);
       process.exitCode = 1;
       return;
     }
@@ -547,27 +571,33 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       configDir: resolvedConfigDir,
       profileName: profileNamePr,
       cwd: process.cwd(),
-      onWarning: (w) => process.stderr.write(w + '\n'),
+      onWarning: (w) => printErrFn(w + '\n'),
       onProfileNotFound: () => {},
     });
 
     const hasAuthPr = connPr.pat || (connPr.email && connPr.apiToken);
     if (!connPr.baseUrl || !hasAuthPr) {
-      process.stderr.write('Error: No Jira credentials found. Run \'ticketlens init\' or set JIRA_BASE_URL + JIRA_API_TOKEN.\n');
+      printErrFn('Error: No Jira credentials found. Run \'ticketlens init\' or set JIRA_BASE_URL + JIRA_API_TOKEN.\n');
       process.exitCode = 1;
       return;
     }
 
     const adapterPr = resolveAdapter(connPr, { fetcher });
+    const complianceRunnerPr = opts.runComplianceCheck ?? runComplianceCheck;
 
     try {
       const md = await assemblePr(ticketKeyArg, {
         configDir: resolvedConfigDir,
         fetchTicketFn: (key, fOpts = {}) => adapterPr.fetchTicket(key, fOpts),
+        // assemblePr's own runComplianceCheckFn default has no stream override
+        // (compliance-checker.mjs's `stream = process.stderr`), so the Pro-gate
+        // upgrade prompt would leak to real stderr unless threaded here — same
+        // treatment as the compliance dispatch block above (`stream: errStream`).
+        runComplianceCheckFn: (o) => complianceRunnerPr({ ...o, stream: errStream }),
       });
       printFn(md + '\n');
     } catch (err) {
-      process.stderr.write(`Error: ${err.message}\n`);
+      printErrFn(`Error: ${err.message}\n`);
       process.exitCode = 1;
     }
     return;
@@ -597,12 +627,12 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   if (args[0] === 'compliance') {
     const ticketKeyArg = args[1];
     if (!ticketKeyArg) {
-      process.stderr.write('Error: "compliance" requires a ticket key. Usage: ticketlens compliance PROJ-123\n');
+      printErrFn('Error: "compliance" requires a ticket key. Usage: ticketlens compliance PROJ-123\n');
       process.exitCode = 1;
       return;
     }
     if (!TICKET_KEY_PATTERN.test(ticketKeyArg)) {
-      process.stderr.write(`Error: "${ticketKeyArg}" is not a valid ticket key. Expected format: PROJ-123\n`);
+      printErrFn(`Error: "${ticketKeyArg}" is not a valid ticket key. Expected format: PROJ-123\n`);
       process.exitCode = 1;
       return;
     }
@@ -626,13 +656,13 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       configDir: resolvedConfigDir,
       profileName: profileNameC,
       cwd: process.cwd(),
-      onWarning: (w) => process.stderr.write(w + '\n'),
+      onWarning: (w) => printErrFn(w + '\n'),
       onProfileNotFound: () => {},
     });
 
     const hasAuthC = connC.pat || (connC.email && connC.apiToken);
     if (!connC.baseUrl || !hasAuthC) {
-      process.stderr.write('Error: No Jira credentials found. Run \'ticketlens init\' or set JIRA_BASE_URL + JIRA_API_TOKEN.\n');
+      printErrFn('Error: No Jira credentials found. Run \'ticketlens init\' or set JIRA_BASE_URL + JIRA_API_TOKEN.\n');
       process.exitCode = 1;
       return;
     }
@@ -643,7 +673,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     try {
       ticketC = await adapterC.fetchTicket(ticketKeyArg, { depth: 0 });
     } catch (err) {
-      process.stderr.write(`Error fetching ${ticketKeyArg}: ${err.message}\n`);
+      printErrFn(`Error fetching ${ticketKeyArg}: ${err.message}\n`);
       process.exitCode = 1;
       return;
     }
@@ -658,6 +688,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       description: ticketC.description,
       ticketKey: ticketKeyArg,
       configDir: resolvedConfigDir,
+      stream: errStream,
     });
 
     if (complianceResult === null) {
@@ -688,7 +719,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     const execFn = opts.execFn ?? spawnSync;
     const cwd = process.cwd();
 
-    const sErr = createStyler({ isTTY: process.stderr.isTTY });
+    const sErr = createStyler({ isTTY });
 
     // Validate flags before any git work
     const reviewFlags = args.slice(1);
@@ -699,28 +730,28 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       // Detect --profile-NAME typo (dash instead of =)
       const profileDashM = flag.match(/^--profile-(.+)$/);
       if (profileDashM) {
-        process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--profile=${profileDashM[1]}`)}?\n`);
+        printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--profile=${profileDashM[1]}`)}?\n`);
         process.exitCode = 1;
         return;
       }
       const baseDashM = flag.match(/^--base-(.+)$/);
       if (baseDashM) {
-        process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--base=${baseDashM[1]}`)}?\n`);
+        printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--base=${baseDashM[1]}`)}?\n`);
         process.exitCode = 1;
         return;
       }
       const branchDashM = flag.match(/^--branch-(.+)$/);
       if (branchDashM) {
-        process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--branch=${branchDashM[1]}`)}?\n`);
+        printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--branch=${branchDashM[1]}`)}?\n`);
         process.exitCode = 1;
         return;
       }
-      process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Usage: ${sErr.cyan('ticketlens review [--base=BRANCH] [--branch=BRANCH] [--profile=NAME]')}\n`);
+      printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Usage: ${sErr.cyan('ticketlens review [--base=BRANCH] [--branch=BRANCH] [--profile=NAME]')}\n`);
       process.exitCode = 1;
       return;
     }
 
-    const spinner = makeSpinner(sErr);
+    const spinner = makeSpinner(sErr, errStream);
     const stderrNotes = [];
 
     // Resolve base branch: --base=BRANCH or auto-detect main/master/develop
@@ -734,7 +765,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       const verifyR = execFn('git', ['rev-parse', '--verify', baseBranch], { encoding: 'utf8', cwd, timeout: 5_000 });
       if (verifyR.status !== 0) {
         spinner.done();
-        process.stderr.write(`${sErr.red('✖')} Branch "${baseBranch}" not found in this repository.\n`);
+        printErrFn(`${sErr.red('✖')} Branch "${baseBranch}" not found in this repository.\n`);
         process.exitCode = 1;
         return;
       }
@@ -772,10 +803,10 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       const profiles = loadProfiles(resolvedConfigDir);
       if (!profiles?.profiles?.[profileNameR]) {
         spinner.done();
-        process.stderr.write(`${sErr.red('✖')} Profile "${profileNameR}" not found.\n`);
+        printErrFn(`${sErr.red('✖')} Profile "${profileNameR}" not found.\n`);
         const names = Object.keys(profiles?.profiles ?? {});
-        if (names.length > 0) process.stderr.write(`  ${sErr.dim('Available:')} ${names.join(', ')}\n`);
-        else process.stderr.write(`  Run ${sErr.cyan('ticketlens init')} to configure a profile.\n`);
+        if (names.length > 0) printErrFn(`  ${sErr.dim('Available:')} ${names.join(', ')}\n`);
+        else printErrFn(`  Run ${sErr.cyan('ticketlens init')} to configure a profile.\n`);
         process.exitCode = 1;
         return;
       }
@@ -817,8 +848,8 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     }
 
     spinner.done();
-    for (const note of stderrNotes) process.stderr.write(note + '\n');
-    if (stderrNotes.length > 0) process.stderr.write('\n');
+    for (const note of stderrNotes) printErrFn(note + '\n');
+    if (stderrNotes.length > 0) printErrFn('\n');
 
     const isLic = opts.isLicensedFn ?? ((tier) => isLicensed(tier, resolvedConfigDir));
     const assembleFn = opts.assemblePrReviewFn ?? assemblePrReview;
@@ -845,7 +876,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     const resolvedConfigDir = configDir ?? (await import('./lib/config.mjs')).DEFAULT_CONFIG_DIR;
     const execFn = opts.execFn ?? spawnSync;
     const cwd = process.cwd();
-    const sErr = createStyler({ isTTY: process.stderr.isTTY });
+    const sErr = createStyler({ isTTY });
 
     const standupFlags = args.slice(1);
 
@@ -856,29 +887,29 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
 
       const sinceDashM = flag.match(/^--since-(.+)$/);
       if (sinceDashM) {
-        process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--since=${sinceDashM[1]}`)}?\n`);
+        printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--since=${sinceDashM[1]}`)}?\n`);
         process.exitCode = 1;
         return;
       }
       const formatDashM = flag.match(/^--format-(.+)$/);
       if (formatDashM) {
-        process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--format=${formatDashM[1]}`)}?\n`);
+        printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--format=${formatDashM[1]}`)}?\n`);
         process.exitCode = 1;
         return;
       }
       const profileDashM = flag.match(/^--profile-(.+)$/);
       if (profileDashM) {
-        process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--profile=${profileDashM[1]}`)}?\n`);
+        printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Did you mean ${sErr.cyan(`--profile=${profileDashM[1]}`)}?\n`);
         process.exitCode = 1;
         return;
       }
       const formatValueM = flag.match(/^--format=(.+)$/);
       if (formatValueM) {
-        process.stderr.write(`${sErr.red('✖')} Invalid --format value: "${formatValueM[1]}". Expected: standup or pr\n`);
+        printErrFn(`${sErr.red('✖')} Invalid --format value: "${formatValueM[1]}". Expected: standup or pr\n`);
         process.exitCode = 1;
         return;
       }
-      process.stderr.write(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Usage: ${sErr.cyan('ticketlens standup [--since=N] [--format=standup|pr] [--profile=NAME]')}\n`);
+      printErrFn(`${sErr.red('✖')} Unknown flag: ${sErr.bold(flag)}\n  Usage: ${sErr.cyan('ticketlens standup [--since=N] [--format=standup|pr] [--profile=NAME]')}\n`);
       process.exitCode = 1;
       return;
     }
@@ -899,16 +930,16 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     if (profileNameS) {
       const profiles = loadProfiles(resolvedConfigDir);
       if (!profiles?.profiles?.[profileNameS]) {
-        process.stderr.write(`${sErr.red('✖')} Profile "${profileNameS}" not found.\n`);
+        printErrFn(`${sErr.red('✖')} Profile "${profileNameS}" not found.\n`);
         const names = Object.keys(profiles?.profiles ?? {});
-        if (names.length > 0) process.stderr.write(`  ${sErr.dim('Available:')} ${names.join(', ')}\n`);
-        else process.stderr.write(`  Run ${sErr.cyan('ticketlens init')} to configure a profile.\n`);
+        if (names.length > 0) printErrFn(`  ${sErr.dim('Available:')} ${names.join(', ')}\n`);
+        else printErrFn(`  Run ${sErr.cyan('ticketlens init')} to configure a profile.\n`);
         process.exitCode = 1;
         return;
       }
     }
 
-    const spinner = makeSpinner(sErr);
+    const spinner = makeSpinner(sErr, errStream);
     const stderrNotes = [];
 
     spinner.update('Scanning git log…');
@@ -955,8 +986,8 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     }
 
     spinner.done();
-    for (const note of stderrNotes) process.stderr.write(note + '\n');
-    if (stderrNotes.length > 0) process.stderr.write('\n');
+    for (const note of stderrNotes) printErrFn(note + '\n');
+    if (stderrNotes.length > 0) printErrFn('\n');
 
     const isPlain = standupFlags.includes('--plain');
     const assembleStandupFn = opts.assembleStandupFn ?? assembleStandup;
@@ -969,12 +1000,12 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
 
   const ticketKey = args.find(a => !a.startsWith('--'));
   if (!ticketKey) {
-    printFetchHelp({ stream: process.stderr });
+    printFetchHelp({ stream: errStream });
     process.exitCode = 1;
     return;
   }
   if (!TICKET_KEY_PATTERN.test(ticketKey)) {
-    process.stderr.write(`Error: "${ticketKey}" is not a valid ticket key. Expected format: PROJ-123\n`);
+    printErrFn(`Error: "${ticketKey}" is not a valid ticket key. Expected format: PROJ-123\n`);
     process.exitCode = 1;
     return;
   }
@@ -982,7 +1013,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   // Normalize --project= alias once at entry so all recursive calls only see --profile=
   const projectArg = args.find(a => a.startsWith('--project='));
   if (projectArg) {
-    process.stderr.write(`Hint: --project recognized as alias for --profile=${projectArg.split('=')[1]}\n\n`);
+    printErrFn(`Hint: --project recognized as alias for --profile=${projectArg.split('=')[1]}\n\n`);
     args = args.map(a => a.startsWith('--project=') ? `--profile=${a.split('=')[1]}` : a);
   }
 
@@ -992,7 +1023,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   const validatedArgs = await handleUnknownFlags(
     args,
     ['--help', '-h', '--plain', '--styled', '--no-attachments', '--no-cache', '--profile=', '--depth=', '--check', '--summarize', '--cloud', '--compliance', '--budget=', '--handoff', '--provider=', '--template='],
-    { hints: ['--stale=', '--status=', '--static'] } // triage-only flags — shown as hints, not applied
+    { hints: ['--stale=', '--status=', '--static'], stream: errStream } // triage-only flags — shown as hints, not applied
   );
   if (validatedArgs === null) { process.exitCode = 1; return; }
   args = validatedArgs;
@@ -1006,7 +1037,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       const tpl = await resolveTemplate(templateSlug, { token: readCliToken(configDir), fetcher });
       templateSections = tpl.sections;
     } catch (err) {
-      process.stderr.write(`Error: ${err.message}\n`);
+      printErrFn(`Error: ${err.message}\n`);
       process.exitCode = 1;
       return;
     }
@@ -1021,10 +1052,11 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       .filter(([, p]) => p.ticketPrefixes?.includes(prefix))
       .map(([name, p]) => ({ name, baseUrl: p.baseUrl || null }));
     if (multiMatches.length > 1) {
-      const picked = await promptMultipleMatches(ticketKey, multiMatches);
+      const promptMultipleMatchesFn = opts.promptMultipleMatchesFn ?? promptMultipleMatches;
+      const picked = await promptMultipleMatchesFn(ticketKey, multiMatches, { stream: errStream });
       if (!picked) { process.exitCode = 1; return; }
       const withProfile = [...args.filter(a => !a.startsWith('--profile=')), `--profile=${picked}`];
-      return run(withProfile, env, fetcher, configDir);
+      return run(withProfile, selfOpts);
     }
   }
 
@@ -1034,18 +1066,19 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     configDir,
     profileName,
     cwd: process.cwd(),
-    onWarning: (w) => process.stderr.write(w + '\n'),
+    onWarning: (w) => printErrFn(w + '\n'),
     onProfileNotFound: (info) => { profileError = info; },
   });
 
   const hasAuth = conn.pat || (conn.email && conn.apiToken);
   if (!conn.baseUrl || !hasAuth) {
     if (profileError) {
-      const picked = await promptProfileSelect(profileError);
+      const promptProfileSelectFn = opts.promptProfileSelectFn ?? promptProfileSelect;
+      const picked = await promptProfileSelectFn(profileError, { stream: errStream });
       if (picked) {
         const newArgs = args.filter(a => !a.startsWith('--profile='));
         newArgs.push(`--profile=${picked}`);
-        return run(newArgs, env, fetcher, configDir);
+        return run(newArgs, selfOpts);
       }
     } else {
       const missing = [];
@@ -1056,7 +1089,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
         : `Missing config in profile "${conn.profileName}": ${missing.join(', ')}`;
       const noProfiles = !loadProfiles(configDir)?.profiles;
       const initHint = noProfiles ? '\nRun `ticketlens init` to set up your connection.' : '';
-      process.stderr.write(`Error: ${hint}${initHint}\n`);
+      printErrFn(`Error: ${hint}${initHint}\n`);
     }
     process.exitCode = 1;
     return;
@@ -1072,10 +1105,11 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       const allProfiles = Object.entries(config?.profiles ?? {})
         .map(([name, p]) => ({ name, baseUrl: p.baseUrl || null }));
       if (allProfiles.length > 1) {
-        const picked = await promptProfileMismatch(ticketKey, conn.profileName, allProfiles);
+        const promptProfileMismatchFn = opts.promptProfileMismatchFn ?? promptProfileMismatch;
+        const picked = await promptProfileMismatchFn(ticketKey, conn.profileName, allProfiles, { stream: errStream });
         if (picked && picked !== conn.profileName) {
           const withProfile = [...args.filter(a => !a.startsWith('--profile=')), `--profile=${picked}`];
-          return run(withProfile, env, fetcher, configDir);
+          return run(withProfile, selfOpts);
         }
       }
     }
@@ -1113,7 +1147,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     if (cached) {
       const s = createStyler({ isTTY: process.stderr.isTTY });
       const age = briefCacheAge(cached.fetchedAt);
-      process.stderr.write(`  ${s.dim('○')} ${s.dim(`${ticketKey} · from cache (${age})  ·  --no-cache to refresh`)}\n\n`);
+      printErrFn(`  ${s.dim('○')} ${s.dim(`${ticketKey} · from cache (${age})  ·  --no-cache to refresh`)}\n\n`);
 
       const allText = [cached.ticket.description, ...cached.ticket.comments.map(c => c.body)].filter(Boolean).join('\n');
       const codeRefs = extractCodeReferences(allText);
@@ -1177,7 +1211,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   }
   // ──────────────────────────────────────────────────────────────────────────
 
-  const session = createSession(conn);
+  const session = createSession(conn, { stream: errStream });
 
   // Load all profiles once for use in the switch-profile retry option.
   const allProfiles = Object.entries(loadProfiles(configDir)?.profiles ?? {})
@@ -1212,23 +1246,28 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       }
 
       if (RETRY_OPTIONS[retryIndex].value === 'switch') {
-        const picked = await promptSwitchProfile(conn.profileName, allProfiles);
+        const promptSwitchProfileFn = opts.promptSwitchProfileFn ?? promptSwitchProfile;
+        const picked = await promptSwitchProfileFn(conn.profileName, allProfiles, { stream: errStream });
         if (picked && picked !== conn.profileName) {
           const withProfile = [...args.filter(a => !a.startsWith('--profile=')), `--profile=${picked}`];
-          return run(withProfile, env, fetcher, configDir);
+          return run(withProfile, selfOpts);
         }
         // Cancelled switch — exit
         process.exitCode = 1;
         return;
       }
 
-      // 'retry' — loop with updated spinner message
+      // 'retry' — loop with updated spinner message. This whole retry-prompt
+      // branch only runs when `!process.stderr.isTTY || !process.stdin.setRawMode`
+      // is false — i.e. never under the MCP server (stdin is always piped there) —
+      // so its remaining process.stderr.write calls are intentionally left
+      // unconverted, dead code under MCP by construction, not an oversight.
       isRetry = true;
       process.stderr.write('\n');
     }
   }
   session.connected();
-  process.stderr.write('\n');
+  printErrFn('\n');
 
   // ── Confluence page fetching ───────────────────────────────────────────────
   // Fetch pages referenced via Jira Remote Links (Confluence-only, non-blocking).
@@ -1276,7 +1315,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
           requirements: extractRequirements(desc),
         };
         const result = dtm.detectDrift(current, prior);
-        if (result.drifted) process.stderr.write(dtm.formatDriftWarning(ticketKey, result.changes));
+        if (result.drifted) printErrFn(dtm.formatDriftWarning(ticketKey, result.changes));
       }
       dtm.writeSnapshot(ticketKey, ticket, { profile: profileName, configDir: resolvedConfigDir, branch });
     }
@@ -1287,14 +1326,14 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     const downloadable = (ticket.attachments ?? []).filter(a => a.content);
     if (downloadable.length > 0) {
       const noun = downloadable.length === 1 ? 'attachment' : 'attachments';
-      process.stderr.write(`Downloading ${downloadable.length} ${noun}…\n`);
+      printErrFn(`Downloading ${downloadable.length} ${noun}…\n`);
       // attachment-downloader is Jira-specific — it needs raw auth headers from buildJiraEnv
       const jiraEnv = buildJiraEnv(conn);
       ticket.localAttachments = await downloadAttachments(ticket, {
         env: jiraEnv,
         fetcher,
         noCache: args.includes('--no-cache'),
-        onProgress: (msg) => process.stderr.write(msg + '\n'),
+        onProgress: (msg) => printErrFn(msg + '\n'),
         allowPrivateIp: conn.allowPrivateIp,
       });
       const downloaded = ticket.localAttachments.filter(r => !r.skipped).length;
@@ -1302,8 +1341,8 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       const parts = [];
       if (downloaded > 0) parts.push(`${downloaded} downloaded`);
       if (cached > 0) parts.push(`${cached} cached`);
-      if (parts.length > 0) process.stderr.write(`  ✓ ${parts.join(', ')}\n`);
-      process.stderr.write('\n');
+      if (parts.length > 0) printErrFn(`  ✓ ${parts.join(', ')}\n`);
+      printErrFn('\n');
     }
   }
 
@@ -1369,7 +1408,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   // Contextual upsell: after a deep traversal with a substantial graph, nudge toward --summarize
   if (depth > 1 && !args.includes('--summarize') && (ticket.linked?.length ?? 0) >= 2) {
     const s = createStyler({ isTTY: process.stderr.isTTY });
-    process.stderr.write(`  ${s.dim('○')} ${s.dim('Tip: large briefs compress further — `--summarize` condenses this to a single AI digest ($8/mo)')}\n`);
+    printErrFn(`  ${s.dim('○')} ${s.dim('Tip: large briefs compress further — `--summarize` condenses this to a single AI digest ($8/mo)')}\n`);
   }
 }
 

package/skills/jtb/scripts/lib/api-utils.mjs

@@ -3,7 +3,7 @@
  * Centralised here to avoid triplicating the regex and warning logic.
  */
 
-export const DEFAULT_API_BASE = 'http://api.ticketlens.test';
+export const DEFAULT_API_BASE = 'https://api.ticketlens.app';
 export const DEFAULT_SITE_BASE = 'https://ticketlens.app';
 
 // Matches localhost, 127.0.0.1, and any hostname ending in .test or .local,

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

@@ -642,18 +642,24 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [
     '',
-    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('mcp')}  ${s.dim('[Pro]')}`,
-    '',
-    `  Start an MCP (Model Context Protocol) stdio server exposing Recall and`,
-    `  ticket writes as native tools — ${s.cyan('recall_add')}, ${s.cyan('recall_search')}, ${s.cyan('ticket_comment')},`,
-    `  ${s.cyan('ticket_transition')}, ${s.cyan('ticket_assign')}, ${s.cyan('ticket_duplicates')}, ${s.cyan('ticket_link')}, ${s.cyan('ticket_update')}, ${s.cyan('ticket_create')} — for any`,
-    `  MCP-compatible AI harness, not just Claude Code. Thin adapter over the same`,
-    `  code as ${s.cyan('note add')}/${s.cyan('recall')}/${s.cyan('comment')}/${s.cyan('transition')}/${s.cyan('assign')}/${s.cyan('duplicates')}/${s.cyan('link')}/${s.cyan('update')}/${s.cyan('create')} above:`,
-    `  same Pro gate, same local vault/tracker writes, same team sync. ${s.cyan('ticket_transition')} is`,
-    `  destructive when called with \`target\`+\`confirm: true\`; ${s.cyan('ticket_assign')} is currently`,
-    `  self-assign only; ${s.cyan('ticket_duplicates')} is read-only; ${s.cyan('ticket_link')} on GitHub closes the`,
-    `  source issue as a duplicate — different semantics than Jira/Linear's relationship-only`,
-    `  add; ${s.cyan('ticket_update')} has no priority field on GitHub and can partially succeed;`,
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('mcp')}`,
+    '',
+    `  Start an MCP (Model Context Protocol) stdio server exposing CLI actions as`,
+    `  native tools — ${s.cyan('fetch')}, ${s.cyan('triage')}, ${s.cyan('compliance')}, ${s.cyan('review')}, ${s.cyan('standup')}, ${s.cyan('pr')}, ${s.cyan('doctor')}, ${s.cyan('recall_add')}, ${s.cyan('recall_search')},`,
+    `  ${s.cyan('ticket_comment')}, ${s.cyan('ticket_transition')}, ${s.cyan('ticket_assign')}, ${s.cyan('ticket_duplicates')}, ${s.cyan('ticket_link')}, ${s.cyan('ticket_update')},`,
+    `  ${s.cyan('ticket_create')} — for any MCP-compatible AI harness, not just Claude Code. Thin`,
+    `  adapter over the same code as ${s.cyan('TICKET-KEY')}/${s.cyan('doctor')}/${s.cyan('triage')}/${s.cyan('compliance')}/${s.cyan('review')}/${s.cyan('standup')}/${s.cyan('pr')}/${s.cyan('note add')}/`,
+    `  ${s.cyan('recall')}/${s.cyan('comment')}/${s.cyan('transition')}/${s.cyan('assign')}/${s.cyan('duplicates')}/${s.cyan('link')}/${s.cyan('update')}/${s.cyan('create')} above.`,
+    `  ${s.cyan('fetch')}, ${s.cyan('doctor')}, and ${s.cyan('standup')} are Free; ${s.cyan('triage')} is Free with some Pro/Team-gated`,
+    `  options (see ${s.cyan('ticketlens triage --help')}); ${s.cyan('compliance')} and ${s.cyan('pr')} are Free, sharing a`,
+    `  3-checks/month cap on their requirements-coverage section, Pro unlimited;`,
+    `  ${s.cyan('review')} is Free for branch/files/ticket context — its coverage/focus section`,
+    `  requires Pro as a plain license check, not a draw on that same counter; every`,
+    `  other tool needs Pro. ${s.cyan('ticket_transition')} is destructive when called with`,
+    `  \`target\`+\`confirm: true\`; ${s.cyan('ticket_assign')} is currently self-assign only;`,
+    `  ${s.cyan('ticket_duplicates')} is read-only; ${s.cyan('ticket_link')} on GitHub closes the source issue as a`,
+    `  duplicate — different semantics than Jira/Linear's relationship-only add;`,
+    `  ${s.cyan('ticket_update')} has no priority field on GitHub and can partially succeed;`,
     `  ${s.cyan('ticket_create')} has no ticket key to target — --profile/the default profile picks the`,
     `  tracker, and it fabricates a real item, the highest blast radius of this family.`,
     `  Long-running — exits when the client closes stdin.`,
@@ -663,9 +669,8 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     `  ${s.dim('restart or reconnect the MCP client to pick up the new schema. The running')}`,
     `  ${s.dim('server is always current; only the client-side copy goes stale.')}`,
     '',
-    `  ${s.dim('The [Pro] badge above describes the tools this server exposes — starting the')}`,
-    `  ${s.dim('server itself is ungated, same as `mcp install`; each tool still enforces its')}`,
-    `  ${s.dim('own license check at call time.')}`,
+    `  ${s.dim('Starting the server itself is ungated, same as `mcp install`; each tool still')}`,
+    `  ${s.dim('enforces its own license check at call time.')}`,
     '',
     `  ${s.bold('OPTIONS')}`,
     '',

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

@@ -25,10 +25,95 @@ 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';
+import { run as runFetchTicket } from '../fetch-ticket.mjs';
+import { run as runTriage } from '../fetch-my-tickets.mjs';
 
 const PROTOCOL_VERSION = '2025-11-25';
 
 const TOOLS = [
+  {
+    name: 'fetch',
+    description: 'Fetch a ticket\'s full context brief (Jira/GitHub/Linear) — description, comments, linked tickets, code references, attachments. The core read action; free tier. Not a discovery tool — requires a known ticket key.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticket: { type: 'string', description: 'Ticket key, e.g. PROJ-123.' },
+        profile: { type: 'string', description: 'Connection profile to target, overriding folder-based inference and the default profile.' },
+        depth: { type: 'number', description: 'How many hops of linked tickets to traverse. Defaults to 1 (direct links only). 0 disables traversal.' },
+      },
+      required: ['ticket'],
+    },
+  },
+  {
+    name: 'triage',
+    description: 'Scan assigned tickets and surface what needs attention — replies owed, aging tickets, stale-status tickets. The base scan is free tier; some options require a TicketLens Pro or Team license.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        profile: { type: 'string', description: 'Connection profile to target, overriding folder-based inference and the default profile.' },
+        stale: { type: 'number', description: 'Days before an untouched ticket counts as aging. Defaults to 5.' },
+        status: { type: 'array', items: { type: 'string' }, description: 'Statuses to include, overriding the profile default / built-in defaults (In Progress, Code Review, QA).' },
+        sort: { type: 'string', description: 'Sort order for results, overriding the profile default.' },
+        save: { type: 'string', description: 'Write the plain-text summary to this local file path instead of (in addition to) returning it. Requires a TicketLens Pro license.' },
+        all: { type: 'boolean', description: 'Triage every configured profile, not just the resolved one. Requires a TicketLens Pro license.' },
+        digest: { type: 'boolean', description: 'Deliver the scored results to the digest backend instead of returning them as text — on success, no summary is returned, only a delivery confirmation. Requires a TicketLens Pro license.' },
+        assignee: { type: 'string', description: 'View another user\'s tickets instead of your own. Requires a TicketLens Team license.' },
+        sprint: { type: 'string', description: 'Scope to a named sprint. Requires a TicketLens Team license.' },
+        export: { type: 'string', enum: ['csv', 'json'], description: 'Write results to a file in this format instead of returning the summary text, returning the written file path instead. Requires a TicketLens Team license.' },
+        project: { type: 'string', description: 'Scope to a project/team key. Requires a TicketLens Team license.' },
+        label: { type: 'array', items: { type: 'string' }, description: 'Scope to one or more labels. Requires a TicketLens Team license.' },
+        priority: { type: 'string', description: 'Scope to a priority name, e.g. "High". Requires a TicketLens Team license.' },
+      },
+    },
+  },
+  {
+    name: 'compliance',
+    description: 'Check a ticket\'s acceptance-criteria coverage against the current git diff — extracts requirements from the ticket description, matches them against code changes, and reports a coverage percentage plus what\'s missing. Read-only; the same check `ticketlens install-hooks` runs automatically. Free tier: 3 checks per month; TicketLens Pro removes the limit.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticket: { type: 'string', description: 'Ticket key, e.g. PROJ-123.' },
+        profile: { type: 'string', description: 'Connection profile to target, overriding folder-based inference and the default profile.' },
+      },
+      required: ['ticket'],
+    },
+  },
+  {
+    name: 'review',
+    description: 'Assemble PR review context from the current git branch — changed files, linked-ticket summaries, and (Pro) a requirements-coverage / review-focus section extracted from the diff against acceptance criteria. Read-only; never modifies the tracker or the repo. Free tier gets branch info, changed files, and ticket context; TicketLens Pro adds the requirements-coverage and review-focus sections — same split as the `compliance` tool.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        base: { type: 'string', description: 'Base branch to diff against. Auto-detects main/master/develop when omitted. Alias of `branch` — if both are given, `base` wins.' },
+        branch: { type: 'string', description: 'Alias for `base` — same effect, provided for parity with the CLI\'s `--branch=` flag.' },
+        profile: { type: 'string', description: 'Connection profile to target, overriding folder-based inference and the default profile.' },
+      },
+    },
+  },
+  {
+    name: 'standup',
+    description: 'Summarize recent git commits grouped by linked ticket — a standup update or, with format:"pr", PR-body-style formatting. Read-only, fully free tier — no license gate on any option.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        since: { type: 'string', description: 'How far back to scan — an integer number of hours ("24") or a git-compatible date expression ("3 days ago"). Defaults to 24 hours.' },
+        format: { type: 'string', enum: ['standup', 'pr'], description: 'Output shape: "standup" (default) groups commits under a per-ticket standup update; "pr" renders the same grouped commits as PR-body-style markdown.' },
+        profile: { type: 'string', description: 'Connection profile to target, overriding folder-based inference and the default profile.' },
+      },
+    },
+  },
+  {
+    name: 'pr',
+    description: 'Assemble a ready-to-paste PR description for a ticket — what changed (from linked commits), linked tickets, and (if the ticket has acceptance criteria) a requirements-coverage section. Read-only. The requirements-coverage section reuses the same Free-tier 3-checks/month counter as the `compliance` tool — calling `pr` on a ticket with acceptance criteria counts against that shared monthly limit; TicketLens Pro removes the cap.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticket: { type: 'string', description: 'Ticket key, e.g. PROJ-123.' },
+        profile: { type: 'string', description: 'Connection profile to target, overriding folder-based inference and the default profile.' },
+      },
+      required: ['ticket'],
+    },
+  },
   {
     name: 'doctor',
     description: 'Diagnose common TicketLens problems: profile configuration, license freshness, tracker connectivity, attachment cache health, MCP registration, and the Recall sync queue. Always returns structured JSON. Free tier, fully unrestricted — including fix.',
@@ -180,6 +265,193 @@ function capturingStream() {
   };
 }
 
+/**
+ * Deliberately v1-minimal — only the three flags with zero cost/AI-provider
+ * implications (see the 49b scoping decision). If `--summarize`/`--handoff`/
+ * `--budget=`/`--compliance`/`--template=` are ever added here, note that
+ * their error/progress output inside fetch-ticket.mjs's bare-fetch path
+ * (applySummarize/applyHandoff/budgetPruner.pruneBrief/showUpgradePrompt)
+ * still writes to the real process.stderr, not the injected printErr —
+ * unlike every path reachable through this function today. Thread printErr
+ * through those call sites first, or their failures will silently collapse
+ * to callFetch's generic 'fetch failed' instead of the real reason.
+ */
+function buildFetchArgs({ ticket, profile, depth }) {
+  const args = [ticket];
+  if (profile) args.push(`--profile=${profile}`);
+  if (depth !== undefined) args.push(`--depth=${depth}`);
+  return args;
+}
+
+/**
+ * Shared by every dispatch that goes through fetch-ticket.mjs's `run()`
+ * (currently `fetch`, `compliance`, `review`, `standup`, and `pr` — all but
+ * `fetch` are subcommands of that same function). `run()` has no {ok} return value
+ * (unlike every other wrapped function) — failure is signaled by mutating
+ * process.exitCode, which is unsafe to read in a long-lived server (one
+ * failed call would poison the whole process's exit code forever). Success
+ * is instead determined by whether `print` ever received real content —
+ * every success path (cache hit, fresh fetch, handoff, a printed report
+ * regardless of pass/fail) calls it exactly once; every failure path
+ * returns before reaching it. errCapture may contain informational
+ * chatter (cache notice, download progress) even on success — only read
+ * on the failure branch, where it carries the actual error message.
+ */
+async function callFetchTicketRun(buildArgsFn, args, { configDir, runFetchTicketFn }, fallbackErrorText) {
+  const capture = capturingStream();
+  const errCapture = capturingStream();
+  await runFetchTicketFn(buildArgsFn(args), {
+    configDir,
+    env: process.env,
+    fetcher: globalThis.fetch,
+    print: capture.write,
+    printErr: errCapture.write,
+  });
+  if (capture.text) {
+    return { content: [{ type: 'text', text: capture.text }] };
+  }
+  return { isError: true, content: [{ type: 'text', text: errCapture.text || fallbackErrorText }] };
+}
+
+async function callFetch(args, deps) {
+  if (!args.ticket) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: ticket' }] };
+  }
+  return callFetchTicketRun(buildFetchArgs, args, deps, 'fetch failed');
+}
+
+/**
+ * Deliberately excludes --push/--share — those sync/share a snapshot as a
+ * human-collaboration side effect (Console notification queue, shareable
+ * link), not "what needs attention" read value. See the 49b scoping memory.
+ */
+function buildTriageArgs({ profile, stale, status, sort, save, all, digest, assignee, sprint, export: exportFormat, project, label, priority }) {
+  const args = ['--plain'];
+  if (profile) args.push(`--profile=${profile}`);
+  if (stale !== undefined) args.push(`--stale=${stale}`);
+  if (Array.isArray(status) && status.length > 0) args.push(`--status=${status.join(',')}`);
+  if (sort) args.push(`--sort=${sort}`);
+  if (save) args.push(`--save=${save}`);
+  if (all === true) args.push('--all');
+  if (digest === true) args.push('--digest');
+  if (assignee) args.push(`--assignee=${assignee}`);
+  if (sprint) args.push(`--sprint=${sprint}`);
+  if (exportFormat) args.push(`--export=${exportFormat}`);
+  if (project) args.push(`--project=${project}`);
+  if (Array.isArray(label) && label.length > 0) args.push(`--label=${label.join(',')}`);
+  if (priority) args.push(`--priority=${priority}`);
+  return args;
+}
+
+/**
+ * runTriage has the same no-{ok}-return architecture as runFetchTicket —
+ * success is "did print receive the summary," failure is whatever landed in
+ * the injected stream. One deliberate exception: `--digest` delivers to the
+ * backend and prints NOTHING to `print` on success (locked by
+ * fetch-my-tickets.test.mjs's own "stdout should be empty" test) — an empty
+ * capture there means delivery succeeded, not that it failed. Only a gate
+ * rejection (Pro license, captured in `stream`) or a thrown delivery error
+ * (caught below) signal an actual digest failure.
+ */
+async function callTriage(args, { configDir, runTriageFn }) {
+  const capture = capturingStream();
+  const errCapture = capturingStream();
+  try {
+    await runTriageFn(buildTriageArgs(args), {
+      configDir,
+      env: process.env,
+      fetcher: globalThis.fetch,
+      print: capture.write,
+      stream: errCapture,
+    });
+  } catch (err) {
+    return { isError: true, content: [{ type: 'text', text: err.message }] };
+  }
+  if (args.digest === true) {
+    if (errCapture.text) {
+      return { isError: true, content: [{ type: 'text', text: errCapture.text }] };
+    }
+    return { content: [{ type: 'text', text: 'Digest delivered.' }] };
+  }
+  if (capture.text) {
+    return { content: [{ type: 'text', text: capture.text }] };
+  }
+  return { isError: true, content: [{ type: 'text', text: errCapture.text || 'triage failed' }] };
+}
+
+/**
+ * `compliance` is a subcommand of the same fetch-ticket.mjs `run()` that
+ * `callFetch` already wraps — reuses `runFetchTicketFn`, no new dependency
+ * or import. See fetch-ticket.mjs's `compliance` dispatch block (thread
+ * printErr through it before this tool existed — see the fetch tool's own
+ * shipping notes for why that treatment was deferred per-tool).
+ */
+function buildComplianceArgs({ ticket, profile }) {
+  const args = ['compliance', ticket];
+  if (profile) args.push(`--profile=${profile}`);
+  return args;
+}
+
+/**
+ * Uses the shared callFetchTicketRun — a below-threshold result is still a
+ * successful check: `run()` prints the report (via `printFn`) before
+ * evaluating the threshold, so a failing coverage percentage is real,
+ * useful report content, not a tool failure. Only the license/usage-gate
+ * case (`runComplianceCheck` returns null) skips the report print entirely
+ * — that's the one path that surfaces as `isError`.
+ */
+async function callCompliance(args, deps) {
+  if (!args.ticket) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: ticket' }] };
+  }
+  return callFetchTicketRun(buildComplianceArgs, args, deps, 'compliance check failed');
+}
+
+/**
+ * `review`/`standup`/`pr` are all subcommands of the same fetch-ticket.mjs
+ * `run()` that `callFetch`/`callCompliance` already wrap — reuse
+ * `runFetchTicketFn`, no new dependency. Each subcommand's error/progress
+ * paths (including makeSpinner's writes) were threaded through opts.printErr
+ * as part of adding these tools — see fetch-ticket.mjs's `review`/`standup`/
+ * `pr` dispatch blocks and makeSpinner's injectable {isTTY, write}.
+ */
+function buildReviewArgs({ base, branch, profile }) {
+  const args = ['review'];
+  if (base) args.push(`--base=${base}`);
+  else if (branch) args.push(`--branch=${branch}`);
+  if (profile) args.push(`--profile=${profile}`);
+  return args;
+}
+
+async function callReview(args, deps) {
+  return callFetchTicketRun(buildReviewArgs, args, deps, 'review failed');
+}
+
+function buildStandupArgs({ since, format, profile }) {
+  const args = ['standup'];
+  if (since !== undefined) args.push(`--since=${since}`);
+  if (format) args.push(`--format=${format}`);
+  if (profile) args.push(`--profile=${profile}`);
+  return args;
+}
+
+async function callStandup(args, deps) {
+  return callFetchTicketRun(buildStandupArgs, args, deps, 'standup failed');
+}
+
+function buildPrArgs({ ticket, profile }) {
+  const args = ['pr', ticket];
+  if (profile) args.push(`--profile=${profile}`);
+  return args;
+}
+
+async function callPr(args, deps) {
+  if (!args.ticket) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: ticket' }] };
+  }
+  return callFetchTicketRun(buildPrArgs, args, deps, 'pr failed');
+}
+
 function buildDoctorArgs({ fix, profile }) {
   const args = ['--format=json'];
   if (fix === true) args.push('--fix');
@@ -403,6 +675,12 @@ async function callTicketCreate(args, { configDir, runTicketCreateFn }) {
 
 async function handleToolsCall(params, deps) {
   const { name, arguments: args = {} } = params ?? {};
+  if (name === 'fetch') return callFetch(args, deps);
+  if (name === 'triage') return callTriage(args, deps);
+  if (name === 'compliance') return callCompliance(args, deps);
+  if (name === 'review') return callReview(args, deps);
+  if (name === 'standup') return callStandup(args, deps);
+  if (name === 'pr') return callPr(args, deps);
   if (name === 'doctor') return callDoctor(args, deps);
   if (name === 'recall_add') return callRecallAdd(args, deps);
   if (name === 'recall_search') return callRecallSearch(args, deps);
@@ -416,7 +694,7 @@ async function handleToolsCall(params, deps) {
   return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
 }
 
-async function handleMessage(raw, { configDir, runDoctorFn, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn }) {
+async function handleMessage(raw, { configDir, runFetchTicketFn, runTriageFn, runDoctorFn, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn }) {
   let msg;
   try {
     msg = JSON.parse(raw);
@@ -446,7 +724,7 @@ async function handleMessage(raw, { configDir, runDoctorFn, runNoteAddFn, runRec
 
   if (method === 'tools/call') {
     try {
-      const result = await handleToolsCall(params, { configDir, runDoctorFn, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn });
+      const result = await handleToolsCall(params, { configDir, runFetchTicketFn, runTriageFn, 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}`);
@@ -467,6 +745,8 @@ export function runMcpServer({
   configDir = DEFAULT_CONFIG_DIR,
   stdin = process.stdin,
   stdout = process.stdout,
+  runFetchTicketFn = runFetchTicket,
+  runTriageFn = runTriage,
   runDoctorFn = runDoctor,
   runNoteAddFn = runNoteAdd,
   runRecallFn = runRecall,
@@ -498,7 +778,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, runDoctorFn, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn });
+      const response = await handleMessage(line, { configDir, runFetchTicketFn, runTriageFn, runDoctorFn, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn });
       if (response) stdout.write(response);
     }).catch(() => {});
   });