ticketlens 0.38.13 → 0.38.14

package/bin/ticketlens.mjs

@@ -35,7 +35,7 @@ import { runStats } from '../skills/jtb/scripts/lib/run-stats.mjs';
 import { createStyler } from '../skills/jtb/scripts/lib/ansi.mjs';
 import { readCliToken, deleteCliToken } from '../skills/jtb/scripts/lib/cli-auth.mjs';
 import { runLogin } from '../skills/jtb/scripts/lib/login-flow.mjs';
-import { syncProfiles, reportSyncResult, getApiBase } from '../skills/jtb/scripts/lib/sync.mjs';
+import { syncProfiles, reportSyncResult, getApiBase, checkTeamMembershipUpdate } from '../skills/jtb/scripts/lib/sync.mjs';
 import { checkForUpdate, getUpdateHint } from '../skills/jtb/scripts/lib/update-check.mjs';
 import { incrementInvocation, incrementCommand } from '../skills/jtb/scripts/lib/activity-counter.mjs';
 import { DEFAULT_CONFIG_DIR } from '../skills/jtb/scripts/lib/config.mjs';
@@ -101,6 +101,7 @@ switch (command) {
   case 'fetch': {
     // Flow 2: fire team config check concurrently; banner shown after brief output
     const _teamCheck = checkTeamJiraConfigUpdate().catch(() => null);
+    const _membershipCheck = checkTeamMembershipUpdate().catch(() => null);
     runFetch(cmdArgs).then(async () => {
       const tcResult = await _teamCheck;
       if (tcResult?.banner) {
@@ -110,6 +111,11 @@ switch (command) {
         const s = createStyler({ isTTY: process.stderr.isTTY });
         process.stderr.write(`\n  ${s.yellow('!')} Team Jira config removed by manager — using local credentials.\n`);
       }
+      const membershipResult = await _membershipCheck;
+      if (membershipResult?.banner) {
+        const s = createStyler({ isTTY: process.stderr.isTTY });
+        process.stderr.write(`\n  ${s.yellow('!')} ${membershipResult.banner}\n`);
+      }
     }).catch(err => {
       process.stderr.write(`Error: ${err.message}\n`);
       process.exitCode = 1;
@@ -364,13 +370,16 @@ switch (command) {
 
     if (cmdArgs[0] === 'set-team') {
       const [, profileName, ...teamNameParts] = cmdArgs;
-      const teamName = teamNameParts.join(' ');
-      if (!profileName || !teamName) {
-        process.stderr.write('Usage: ticketlens profiles set-team <profile> <team name>\n');
+      const teamName = teamNameParts.length > 0 ? teamNameParts.join(' ') : undefined;
+      if (!profileName) {
+        process.stderr.write('Usage: ticketlens profiles set-team <profile> [team name]\n');
         process.exitCode = 1;
         break;
       }
-      runProfilesSetTeam(profileName, teamName);
+      runProfilesSetTeam(profileName, teamName).catch(err => {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exitCode = 1;
+      });
       break;
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.38.13",
+  "version": "0.38.14",
   "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/scripts/lib/ansi.mjs

@@ -86,5 +86,19 @@ export const brightCyan   = defaultStyler.brightCyan;
 export const brand        = defaultStyler.brand;
 export const isStyled     = () => defaultStyler.enabled;
 
-export const ANSI_RE = /\[[0-9;]*m/g;
+export const ANSI_RE = /\x1b\[[0-9;]*m/g;
 export function stripAnsi(s) { return s.replace(ANSI_RE, ''); }
+
+// Strips ALL C0/C1 control characters and DEL — not just this app's own SGR
+// color codes (stripAnsi above only covers ESC [ ... m, not the broader
+// escape grammar: OSC, cursor movement, etc.). Apply to any server-supplied
+// string before it ever reaches a terminal write — e.g. a Console team name,
+// which is attacker-controlled (any self-registered user's account name)
+// and unfiltered server-side beyond a bare length check.
+export function sanitizeUntrustedText(s) {
+  if (typeof s !== 'string') return '';
+  return Array.from(s).filter((ch) => {
+    const code = ch.codePointAt(0);
+    return !((code >= 0x00 && code <= 0x1f) || (code >= 0x7f && code <= 0x9f));
+  }).join('');
+}

package/skills/jtb/scripts/lib/config-wizard.mjs

@@ -449,7 +449,14 @@ export async function run({ configDir = DEFAULT_CONFIG_DIR, profileName } = {})
   if (isTrustedForCurrentUrl()) updated.allowPrivateIp = true;
   else delete updated.allowPrivateIp;
 
-  const credData = (token !== existingToken)
+  // Also write on an auth-type switch even when the typed token text is
+  // unchanged — a Server/DC PAT can double as a Basic-auth password, so
+  // `basic` -> `pat` with the same secret is a real flow, not contrived.
+  // Gating on token identity alone left the stale old-type field (apiToken
+  // or pat) sitting in credentials.json indefinitely; saveProfile()'s merge
+  // only clears the opposite field when the corresponding new key is
+  // actually present in credData.
+  const credData = (token !== existingToken || auth !== profile.auth)
     ? (auth === 'pat' ? { pat: token } : { apiToken: token })
     : {};
 

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

@@ -13,7 +13,7 @@ import { scanForSecrets } from './secret-scanner.mjs';
 import { checkNoteStructure } from './note-structural-check.mjs';
 import { writeNote, patchNoteBody, deleteNote, deleteNoteAnyPrefix, rebuildIndex } from './recall-vault.mjs';
 import { readCliToken } from './cli-auth.mjs';
-import { resolveProfile } from './profile-resolver.mjs';
+import { resolveProfile, loadProfileRecallTeamId } from './profile-resolver.mjs';
 import { pushNote } from './recall-sync.mjs';
 import { enqueueNote, isRetryableFailure, maybeAutoFlush } from './recall-queue.mjs';
 import { incrementDraftKept, incrementDraftDeleted } from './activity-counter.mjs';
@@ -75,6 +75,7 @@ export async function runNoteAdd(cmdArgs, {
   writeNoteFn = writeNote,
   readCliTokenFn = readCliToken,
   resolveProfileFn = resolveProfile,
+  loadProfileRecallTeamIdFn = loadProfileRecallTeamId,
   pushNoteFn = pushNote,
   enqueueNoteFn = enqueueNote,
   isRetryableFailureFn = isRetryableFailure,
@@ -142,8 +143,9 @@ export async function runNoteAdd(cmdArgs, {
     // Field names match PushRequest's validation rules (external_id, tickets) —
     // the backend wire contract, not the local vault's internal camelCase shape.
     const profile = resolveProfileFn(ticketKey || null, { configDir, cwd: process.cwd() });
+    const recallTeamId = profile ? loadProfileRecallTeamIdFn(profile.name, configDir) : null;
     const payload = { external_id: id, title, tickets: ticketKeys, tags, author, sources: [], body };
-    if (profile?.recallTeam) payload.group = profile.recallTeam;
+    if (recallTeamId !== null) payload.group_id = recallTeamId;
     const result = await pushNoteFn(payload, { cliToken, configDir, warn });
     if (isRetryableFailureFn(result)) {
       await enqueueNoteFn(payload, { cliToken, configDir, warn });

package/skills/jtb/scripts/lib/profile-resolver.mjs

@@ -7,6 +7,7 @@ import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync } from 'no
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { sanitizeUntrustedText } from './ansi.mjs';
 
 /** Simple Levenshtein distance for "did you mean" suggestions. */
 function levenshtein(a, b) {
@@ -24,7 +25,7 @@ function levenshtein(a, b) {
   return dp[m];
 }
 
-function findClosest(input, candidates) {
+export function findClosest(input, candidates) {
   if (candidates.length === 0) return null;
   const lower = input.toLowerCase();
   let best = null;
@@ -55,13 +56,18 @@ export function saveDefault(name, configDir = DEFAULT_CONFIG_DIR) {
   invalidateProfilesCache(configDir);
 }
 
-// Team list synced from /v1/profiles — used to validate `recallTeam` on a
-// profile without a live network call at push/pull time. Not credentials.
+// Team list synced from /v1/profiles — used to resolve a typed team name to
+// its id in `ticketlens profiles set-team` without a live network call.
+// Not credentials (the resulting recallTeamId is — see saveProfileRecallTeamId).
 export function saveTeams(teams, configDir = DEFAULT_CONFIG_DIR) {
   mkdirSync(configDir, { recursive: true });
   const profilesPath = join(configDir, 'profiles.json');
   const config = loadProfiles(configDir) || { profiles: {} };
-  config.teams = teams;
+  // A team's name is server-supplied and traces back to another user's own
+  // account name (Group::createForOwner) — unfiltered, attacker-influenceable
+  // text. Sanitized here, at the single write path, so every consumer
+  // (picker, banners, set-team messages) is safe without having to remember to.
+  config.teams = teams.map(t => ({ ...t, name: sanitizeUntrustedText(t.name) }));
   writeFileSync(profilesPath, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
   invalidateProfilesCache(configDir);
 }
@@ -79,12 +85,38 @@ export function saveProfile(name, profileData, credData, configDir = DEFAULT_CON
   if (credData && Object.keys(credData).length > 0) {
     const credPath = join(configDir, 'credentials.json');
     const creds = loadCredentials(configDir);
-    creds[name] = credData;
+    // Merge, not replace — a caller re-saving apiToken/pat must never silently
+    // drop an unrelated field already stored on this profile (e.g. recallTeamId).
+    // But apiToken and pat are mutually exclusive auth methods, never both
+    // active at once — setting one must clear a stale copy of the other, or
+    // switching auth type would leave a rotated/revoked credential sitting
+    // in the sensitive-tier file indefinitely.
+    const merged = { ...(creds[name] || {}), ...credData };
+    if ('apiToken' in credData) delete merged.pat;
+    if ('pat' in credData) delete merged.apiToken;
+    creds[name] = merged;
     writeFileSync(credPath, JSON.stringify(creds, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
   }
   invalidateProfilesCache(configDir);
 }
 
+// recallTeamId lives in credentials.json (not profiles.json) — it's a
+// sensitive association (which specific Console team a specific local
+// profile/folder routes Recall notes to), not the non-secret profile shape
+// that credentials.json's sibling fields (baseUrl, prefixes) already are.
+export function saveProfileRecallTeamId(name, teamId, configDir = DEFAULT_CONFIG_DIR) {
+  mkdirSync(configDir, { recursive: true });
+  const credPath = join(configDir, 'credentials.json');
+  const creds = loadCredentials(configDir);
+  creds[name] = { ...(creds[name] || {}), recallTeamId: teamId };
+  writeFileSync(credPath, JSON.stringify(creds, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+  invalidateProfilesCache(configDir);
+}
+
+export function loadProfileRecallTeamId(name, configDir = DEFAULT_CONFIG_DIR) {
+  return loadCredentials(configDir)[name]?.recallTeamId ?? null;
+}
+
 export function deleteProfile(name, configDir = DEFAULT_CONFIG_DIR) {
   const profilesPath = join(configDir, 'profiles.json');
   const config = loadProfiles(configDir);

package/skills/jtb/scripts/lib/profile-set-team.mjs

@@ -1,22 +1,26 @@
 /**
  * ticketlens profiles set-team — maps a local Jira profile to the Console
- * team its Recall notes should push/pull against. Validates the name
- * against the locally synced team list (no live network call — that list
- * is refreshed by `ticketlens login`/`ticketlens sync`), but never blocks
- * the write on a stale/missing list or a name mismatch: the hard check is
- * server-side at push/pull time (RecallTeamResolver), this is a local
- * convenience check only.
+ * team its Recall notes should push/pull against. Stores the team's id in
+ * credentials.json (not profiles.json) — this is a sensitive association
+ * (which specific team a specific local profile/folder routes notes to),
+ * distinct from the non-secret profile shape profiles.json already carries.
+ * Resolved against the locally synced team list (refreshed by
+ * `ticketlens login`/`ticketlens sync`) — no live network call here, but
+ * never a blind write either: an unresolvable name errors instead of
+ * storing an id that doesn't exist.
  */
 import { createStyler } from './ansi.mjs';
-import { loadProfiles, loadTeams, saveProfile } from './profile-resolver.mjs';
+import { loadProfiles, loadTeams, saveProfileRecallTeamId, findClosest } from './profile-resolver.mjs';
+import { promptSelect } from './select-prompt.mjs';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
 
-export function runProfilesSetTeam(profileName, teamName, {
+export async function runProfilesSetTeam(profileName, teamName, {
   configDir = DEFAULT_CONFIG_DIR,
   stream = process.stderr,
   loadProfilesFn = loadProfiles,
   loadTeamsFn = loadTeams,
-  saveProfileFn = saveProfile,
+  saveProfileRecallTeamIdFn = saveProfileRecallTeamId,
+  promptSelectFn = promptSelect,
 } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const config = loadProfilesFn(configDir);
@@ -30,12 +34,36 @@ export function runProfilesSetTeam(profileName, teamName, {
 
   const teams = loadTeamsFn(configDir);
   if (teams.length === 0) {
-    stream.write(`  ${s.yellow('⚠')} No synced teams found — run ${s.cyan('ticketlens sync')} first to validate this name.\n`);
-  } else if (!teams.some(t => t.name === teamName)) {
-    stream.write(`  ${s.yellow('⚠')} "${teamName}" isn't one of your synced teams — check spelling, or run ${s.cyan('ticketlens sync')} to refresh.\n`);
+    stream.write(`  ${s.red('✖')} No synced teams found. Run ${s.cyan('ticketlens sync')} first.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let team;
+  if (teamName) {
+    team = teams.find(t => t.name === teamName);
+    if (!team) {
+      const suggestion = findClosest(teamName, teams.map(t => t.name));
+      stream.write(`  ${s.red('✖')} "${teamName}" isn't one of your synced teams.\n`);
+      if (suggestion) stream.write(`  ${s.dim('Did you mean')} ${s.cyan(suggestion)}${s.dim('?')}\n`);
+      process.exitCode = 1;
+      return;
+    }
+  } else if (!stream.isTTY) {
+    stream.write(`  ${s.red('✖')} No team specified. Pass a team name, or run this interactively to pick one:\n`);
+    for (const t of teams) stream.write(`    ${s.cyan(t.name)} ${s.dim(`(${t.role})`)}\n`);
+    process.exitCode = 1;
+    return;
+  } else {
+    const items = teams.map(t => ({ label: t.name, sublabel: t.role }));
+    const index = await promptSelectFn(items, { stream });
+    if (index === null) {
+      stream.write(`  ${s.dim('Cancelled.')}\n`);
+      return;
+    }
+    team = teams[index];
   }
 
-  // Must merge, not replace — saveProfile() overwrites the whole profile object.
-  saveProfileFn(profileName, { ...profile, recallTeam: teamName }, null, configDir);
-  stream.write(`  ${s.green('✔')} Recall notes captured under ${s.bold(s.cyan(profileName))} will target ${s.bold(s.cyan(teamName))}.\n`);
+  saveProfileRecallTeamIdFn(profileName, team.id, configDir);
+  stream.write(`  ${s.green('✔')} Recall notes captured under ${s.bold(s.cyan(profileName))} will target ${s.bold(s.cyan(team.name))}.\n`);
 }

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

@@ -15,7 +15,7 @@ import { TICKET_KEY_PATTERN } from './cli.mjs';
 import { isLicensed, showUpgradePrompt } from './license.mjs';
 import { listNotes } from './recall-vault.mjs';
 import { readCliToken } from './cli-auth.mjs';
-import { resolveProfile } from './profile-resolver.mjs';
+import { resolveProfile, loadProfileRecallTeamId } from './profile-resolver.mjs';
 import { pullNotes } from './recall-sync.mjs';
 import { maybeAutoFlush, flushQueue, readQueue } from './recall-queue.mjs';
 import { getEffectiveRecallSettingsWithSource } from './recall-settings-sync.mjs';
@@ -33,6 +33,7 @@ export async function runRecall(cmdArgs, {
   listNotesFn = listNotes,
   readCliTokenFn = readCliToken,
   resolveProfileFn = resolveProfile,
+  loadProfileRecallTeamIdFn = loadProfileRecallTeamId,
   pullNotesFn = pullNotes,
   maybeAutoFlushFn = maybeAutoFlush,
 } = {}) {
@@ -52,7 +53,8 @@ export async function runRecall(cmdArgs, {
   const cliToken = readCliTokenFn(configDir);
   if (cliToken) {
     const profile = resolveProfileFn(isTicketKey ? arg : null, { configDir, cwd: process.cwd() });
-    await pullNotesFn({ cliToken, configDir, ttlMs: 0, group: profile?.recallTeam });
+    const recallTeamId = profile ? loadProfileRecallTeamIdFn(profile.name, configDir) : null;
+    await pullNotesFn({ cliToken, configDir, ttlMs: 0, groupId: recallTeamId ?? undefined });
     await maybeAutoFlushFn({ cliToken, configDir });
   }
 

package/skills/jtb/scripts/lib/recall-sync.mjs

@@ -79,17 +79,18 @@ function writeEntitlementCheckedAt(configDir, isoTimestamp, cliToken) {
 }
 
 // Shared by pushNote's and pullNotes' 422 handling — a profile's configured
-// recallTeam that doesn't match any of this account's Console teams
-// (renamed/removed/typo) must never silently drop a note or return zero
-// pull results; both retry once against the account's default team instead.
+// recallTeamId that no longer matches any of this account's Console teams
+// (team deleted, or the account was removed from it) must never silently
+// drop a note or return zero pull results; both retry once against the
+// account's default team instead.
 async function isUnknownTeamRejection(res) {
   let reason;
   try { reason = (await res.json())?.error; } catch { /* not this case — fall through */ }
   return reason === 'Unknown team';
 }
 
-function warnUnknownTeam(warn, groupName, fallbackAction) {
-  warn(`  ${yellow('⚠')} "${groupName}" isn't a team on your account — ${fallbackAction} instead.\n  ${dim('→ Run')} ${cyan('ticketlens profiles set-team')} ${dim('to fix this profile\'s team mapping.')}\n`);
+function warnUnknownTeam(warn, groupId, fallbackAction) {
+  warn(`  ${yellow('⚠')} Team #${groupId} isn't a team on your account — ${fallbackAction} instead.\n  ${dim('→ Run')} ${cyan('ticketlens profiles set-team')} ${dim('to fix this profile\'s team mapping.')}\n`);
 }
 
 /**
@@ -182,9 +183,9 @@ export async function pushNote(note, {
     return { ok: false, status: res.status };
   }
 
-  if (res.status === 422 && note.group !== undefined && await isUnknownTeamRejection(res)) {
-    warnUnknownTeam(warn, note.group, 'saved to your default team');
-    const { group: _omit, ...withoutGroup } = note;
+  if (res.status === 422 && note.group_id !== undefined && await isUnknownTeamRejection(res)) {
+    warnUnknownTeam(warn, note.group_id, 'saved to your default team');
+    const { group_id: _omit, ...withoutGroup } = note;
     let retryRes;
     try {
       retryRes = await post(withoutGroup);
@@ -212,7 +213,7 @@ export async function pushNote(note, {
  * @param {string}   [opts.configDir]
  * @param {number}   [opts.ttlMs] - skip the network call if the last pull is more recent than this
  * @param {number}   [opts.timeoutMs] - request timeout; short for a passive/background pull, long for an explicit one
- * @param {string}   [opts.group] - explicit target team name, for accounts on more than one team
+ * @param {number}   [opts.groupId] - explicit target team id, for accounts on more than one team
  * @param {Function} [opts.fetcher]
  * @param {Function} [opts.warn] - failure output (default: process.stderr.write)
  * @param {Function} [opts.upsertPulledNoteFn]
@@ -225,7 +226,7 @@ export async function pullNotes({
   configDir = DEFAULT_CONFIG_DIR,
   ttlMs = RECALL_PULL_TTL_MS,
   timeoutMs = 15_000,
-  group,
+  groupId,
   fetcher = globalThis.fetch,
   warn = (s) => process.stderr.write(s),
   upsertPulledNoteFn = upsertPulledNote,
@@ -242,13 +243,13 @@ export async function pullNotes({
     return { ok: true, skipped: true, count: 0 };
   }
 
-  const buildUrl = (targetGroup) => {
+  const buildUrl = (targetGroupId) => {
     const url = new URL(`${apiBase()}${PULL_PATH}`);
     if (lastPulledAt) url.searchParams.set('since', lastPulledAt);
-    if (targetGroup) url.searchParams.set('group', targetGroup);
+    if (targetGroupId !== undefined) url.searchParams.set('group_id', targetGroupId);
     return url.toString();
   };
-  const get = (targetGroup) => fetcher(buildUrl(targetGroup), {
+  const get = (targetGroupId) => fetcher(buildUrl(targetGroupId), {
     headers: { 'Authorization': `Bearer ${cliToken}`, 'Accept': 'application/json' },
     redirect: 'manual',
     signal: AbortSignal.timeout(timeoutMs),
@@ -256,13 +257,13 @@ export async function pullNotes({
 
   let res;
   try {
-    res = await get(group);
+    res = await get(groupId);
   } catch {
     return { ok: false, count: 0 };
   }
 
-  if (!res.ok && res.status === 422 && group !== undefined && await isUnknownTeamRejection(res)) {
-    warnUnknownTeam(warn, group, 'pulling from your default team');
+  if (!res.ok && res.status === 422 && groupId !== undefined && await isUnknownTeamRejection(res)) {
+    warnUnknownTeam(warn, groupId, 'pulling from your default team');
     try {
       res = await get(undefined);
     } catch {

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

@@ -11,11 +11,12 @@ import {
   loadCredentials,
   saveProfile,
   saveTeams,
+  loadTeams,
   invalidateProfilesCache,
 } from './profile-resolver.mjs';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { apiBase } from './api-utils.mjs';
-import { createStyler } from './ansi.mjs';
+import { createStyler, sanitizeUntrustedText } from './ansi.mjs';
 
 export const getApiBase     = () => apiBase();
 // Strip the api. subdomain to get the console base URL (e.g. api.ticketlens.app → ticketlens.app)
@@ -127,6 +128,69 @@ export async function syncProfiles({
   return { added, updated, unchanged, needsCredentials };
 }
 
+/**
+ * Fire-and-forget check for team membership drift (invited to a new team,
+ * removed from one) — same shape as team-jira-sync.mjs's
+ * checkTeamJiraConfigUpdate, reusing the same /v1/profiles endpoint
+ * syncProfiles() already calls rather than a live-diff-only 403/404 branch.
+ * Never blocks or throws — a background check must never break the actual
+ * command it's riding alongside.
+ *
+ * @param {object} [opts]
+ * @param {string}   [opts.configDir]
+ * @param {Function} [opts.fetcher]
+ * @returns {Promise<{updated: boolean, banner?: string}>}
+ */
+export async function checkTeamMembershipUpdate({ configDir = DEFAULT_CONFIG_DIR, fetcher = globalThis.fetch } = {}) {
+  const token = readCliToken(configDir);
+  if (!token) return { updated: false };
+
+  let res;
+  try {
+    res = await fetcher(`${getApiBase()}/v1/profiles`, {
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+      signal: AbortSignal.timeout(10000),
+    });
+  } catch {
+    return { updated: false };
+  }
+  if (!res.ok) return { updated: false };
+
+  let json;
+  try { json = await res.json(); } catch { return { updated: false }; }
+
+  // Sanitized immediately on receipt — remoteTeams feeds both the banner
+  // text below (built before saveTeams' own sanitization would ever run)
+  // and the persisted cache, so both must see the cleaned name.
+  const remoteTeams = (Array.isArray(json?.teams) ? json.teams : [])
+    .map(t => ({ ...t, name: sanitizeUntrustedText(t.name) }));
+  const localTeams  = loadTeams(configDir);
+  const localIds    = new Set(localTeams.map(t => t.id));
+  const remoteIds   = new Set(remoteTeams.map(t => t.id));
+
+  const added   = remoteTeams.filter(t => !localIds.has(t.id));
+  const removed = localTeams.filter(t => !remoteIds.has(t.id));
+  // A rename or role change (same id, different name/role) is neither an
+  // add nor a remove, but the stale local copy must not be left behind.
+  const changed = remoteTeams.some(t => {
+    const local = localTeams.find(l => l.id === t.id);
+    return local && (local.name !== t.name || local.role !== t.role);
+  });
+
+  if (added.length === 0 && removed.length === 0 && !changed) return { updated: false };
+
+  saveTeams(remoteTeams, configDir);
+
+  if (added.length === 0 && removed.length === 0) return { updated: false };
+
+  const lines = [
+    ...added.map(t => `You now have access to "${t.name}" — link a profile with: ticketlens profiles set-team <profile> "${t.name}"`),
+    ...removed.map(t => `You no longer have access to "${t.name}".`),
+  ];
+
+  return { updated: true, banner: lines.join('\n  ') };
+}
+
 /**
  * Formats a syncProfiles() result to a stream. Shared by `ticketlens sync`
  * and the onboarding hub's "Console login" step so both report the same