testronaut 1.5.0 → 1.6.0

package/bin/cli.js

@@ -51,6 +51,8 @@ const exec = promisify(execCmd);
 import url from 'url';
 import { ensureBrowsers } from '../tools/playwrightSetup.js';
 import { discoverMissionFiles } from '../core/missionDiscovery.js';
+import { loadConfig } from '../core/config.js';
+import { matchesTagFilter, normalizeTagMatch, normalizeTags } from '../core/tags.js';
 
 // Keep PW browsers inside the project to avoid global cache skew
 process.env.PLAYWRIGHT_BROWSERS_PATH = process.env.PLAYWRIGHT_BROWSERS_PATH || '0';
@@ -311,6 +313,61 @@ export const __test__ = {
   isDirectInvocation,
 };
 
+function parseTagArgs(argsList) {
+  const nextArgs = [];
+  const tagValues = [];
+  const addTagValues = [];
+  let tagMatchValue;
+  let tagsPresent = false;
+  let addTagsPresent = false;
+  let tagMatchPresent = false;
+  let tagsMissingValue = false;
+  let addTagsMissingValue = false;
+
+  const matchFlag = (raw, names) => names.some(name => raw === name || raw.startsWith(`${name}=`));
+  const readValue = (raw, index) => {
+    if (raw.includes('=')) return { value: raw.slice(raw.indexOf('=') + 1), consumed: 1 };
+    const candidate = argsList[index + 1];
+    return candidate && !candidate.startsWith('-')
+      ? { value: candidate, consumed: 2 }
+      : { value: undefined, consumed: 1 };
+  };
+
+  for (let index = 0; index < argsList.length;) {
+    const raw = argsList[index];
+    if (matchFlag(raw, ['--tag', '--tags'])) {
+      const { value, consumed } = readValue(raw, index);
+      tagsPresent = true;
+      if (value !== undefined) tagValues.push(value);
+      else tagsMissingValue = true;
+      index += consumed;
+    } else if (matchFlag(raw, ['--add-tag', '--add-tags', '--add_tag', '--add_tags'])) {
+      const { value, consumed } = readValue(raw, index);
+      addTagsPresent = true;
+      if (value !== undefined) addTagValues.push(value);
+      else addTagsMissingValue = true;
+      index += consumed;
+    } else if (matchFlag(raw, ['--tag-match', '--tag_match'])) {
+      const { value, consumed } = readValue(raw, index);
+      tagMatchPresent = true;
+      tagMatchValue = value;
+      index += consumed;
+    } else {
+      nextArgs.push(raw);
+      index += 1;
+    }
+  }
+
+  return {
+    args: nextArgs,
+    tags: { present: tagsPresent, value: tagValues.length ? tagValues.join(',') : undefined, missingValue: tagsMissingValue },
+    addTags: { present: addTagsPresent, value: addTagValues.length ? addTagValues.join(',') : undefined, missingValue: addTagsMissingValue },
+    tagMatch: { present: tagMatchPresent, value: tagMatchValue },
+    hasUnquotedCommaSpace: [...tagValues, ...addTagValues].some(value => value.trimEnd().endsWith(',')),
+  };
+}
+__test__.parseTagArgs = parseTagArgs;
+
 // Look for --model=<id> or --model <id>
 let modelOverride;
 const modelFlagIndex = args.findIndex(a => a === '--model' || a.startsWith('--model='));
@@ -356,6 +413,26 @@ if (cliMfaName) {
   console.log(`🔐 MFA nickname override: ${process.env.TESTRONAUT_MFA_NAME}`);
 }
 
+const tagArgs = parseTagArgs(args);
+args = tagArgs.args;
+let cliTags;
+let cliAddTags = [];
+let cliTagMatch;
+try {
+  if (tagArgs.hasUnquotedCommaSpace) {
+    throw new Error('A tag list ends with a comma. Quote comma-and-space lists (for example --tags "authentication, smoke") or repeat --tag for each tag.');
+  }
+  if (tagArgs.tags.missingValue || (tagArgs.tags.present && !tagArgs.tags.value)) throw new Error('--tag/--tags requires a tag value.');
+  if (tagArgs.addTags.missingValue || (tagArgs.addTags.present && !tagArgs.addTags.value)) throw new Error('--add-tag/--add-tags requires a tag value.');
+  if (tagArgs.tagMatch.present && !tagArgs.tagMatch.value) throw new Error('--tag-match requires "any" or "all".');
+  if (tagArgs.tags.present) cliTags = normalizeTags(tagArgs.tags.value, { allowUntagged: true });
+  if (tagArgs.addTags.present) cliAddTags = normalizeTags(tagArgs.addTags.value);
+  if (tagArgs.tagMatch.present) cliTagMatch = normalizeTagMatch(tagArgs.tagMatch.value);
+} catch (error) {
+  console.error(`❌ ${error.message}`);
+  process.exit(1);
+}
+
 // Look for --debug / --debug=<bool> / --no-debug
 // Normalize CLI boolean strings into true/false/null for optional flags.
 const parseBool = (v) => {
@@ -545,6 +622,11 @@ Options:
   --human-input-timeout=<s> Override human input wait timeout in seconds (default: 60)
   --help                    Show this help message
   --retry_limit=<n>         Override agent turn retry limits (minimum 1, maximum 10)
+  --tag=<tag>               Run missions matching a tag; repeat for multiple tags
+  --tags=<tag,...>          Compact comma-list form (OR/any by default)
+  --tag-match=<any|all>     Match any or all requested tags
+  --add-tag=<tag>           Add one report tag; repeat for multiple tags
+  --add-tags=<tag,...>      Compact comma-list form for report tags
 
 Examples:
   ${cliName}
@@ -552,6 +634,8 @@ Examples:
   ${cliName} upload
   ${cliName} serve
   ${cliName} --init
+  ${cliName} --tag authentication --tag smoke
+  ${cliName} --add-tag staging --add-tag full-test-run
 `;
 
 async function main() {
@@ -619,6 +703,21 @@ if (args.includes('serve') || args.includes('view')) {
 }
 
 const { root: missionsRoot, files: discoveredMissions } = await discoverMissionFiles({ cwd: process.cwd() });
+const tagConfig = await loadConfig(process.cwd());
+const explicitFiles = args.length > 0;
+let requestedTags = [];
+let tagMatch = 'any';
+try {
+  requestedTags = explicitFiles ? [] : (cliTags ?? normalizeTags(tagConfig?.tags, { allowUntagged: true }));
+  tagMatch = explicitFiles ? 'any' : normalizeTagMatch(cliTagMatch ?? tagConfig?.tagMatch);
+  process.env.TESTRONAUT_ADD_TAGS = normalizeTags([
+    ...normalizeTags(tagConfig?.addTags),
+    ...cliAddTags,
+  ]).join(',');
+} catch (error) {
+  console.error(`❌ ${error.message}`);
+  process.exit(1);
+}
 
 if (!fs.existsSync(missionsRoot)) {
   console.error(`❌ Missions directory not found: ${path.relative(process.cwd(), missionsRoot)}`);
@@ -630,17 +729,24 @@ const runFile = async (filePath) => {
     const modulePath = path.resolve(missionsRoot, filePath);
     const missionsModule = await import(`file://${modulePath}`);
 
+    if (!explicitFiles) {
+      const moduleTags = normalizeTags(missionsModule.tags);
+      if (!matchesTagFilter(moduleTags, requestedTags, tagMatch)) return false;
+    }
+
     if (typeof missionsModule.executeMission === 'function') {
       const result = await missionsModule.executeMission();
       allResults.push({
         file: filePath,
         result
       });
+      return true;
     }
   } catch (err) {
     console.error(`❌ Error running mission: ${filePath}`);
     console.error(err);
   }
+  return false;
 };
 
 if (args.length > 0) {
@@ -655,6 +761,11 @@ if (args.length > 0) {
   }
 }
 
+if (!explicitFiles && requestedTags.length && allResults.length === 0) {
+  console.error(`❌ No missions matched ${tagMatch === 'all' ? 'all' : 'any'} of: ${requestedTags.join(', ')}`);
+  process.exit(1);
+}
+
 const endTime = new Date();
 
 const flatMissions = allResults.flatMap(entry => {
@@ -696,6 +807,9 @@ const report = {
   },
   missions: flatMissions
 };
+report.tags = normalizeTags(flatMissions.flatMap(m =>
+  m.submissionType === 'mission' ? (m.tags ?? []) : []
+));
 
 const outputDir = './missions/mission_reports';
 fs.mkdirSync(outputDir, { recursive: true });

package/bin/createWelcomeMission.js

@@ -15,7 +15,9 @@ export const createWelcomeMission = async () => {
     return;
   }
 
-  const content = `import { runMissions } from 'testronaut';
+const content = `import { runMissions } from 'testronaut';
+
+export const tags = [];
 
 const welcomeGoal = \`
 Welcome to Testronaut!
@@ -29,7 +31,8 @@ If you cannot reach this message, report FAILURE.
 
 export async function executeMission() {
   return await runMissions({
-    mission: welcomeGoal
+    mission: welcomeGoal,
+    tags
   }, 'Welcome Mission!');
 }
 

package/bin/initHelpers.js

@@ -54,6 +54,9 @@ export function defaultConfig(rootBasename) {
     outputDir: 'missions/mission_reports',
     projectName: rootBasename,
     maxTurns: 20,
+    tags: [],
+    tagMatch: 'any',
+    addTags: [],
     dom: {
       listItemLimit: 3,
     },

package/core/tags.js

@@ -0,0 +1,50 @@
+export const TAG_PATTERN = /^[a-z0-9_-]+$/;
+export const MAX_TAG_LENGTH = 40;
+export const MAX_TAGS_PER_MISSION = 50;
+export const UNTAGGED_FILTER = 'untagged';
+
+export function normalizeTag(value) {
+  const tag = String(value ?? '').trim().toLowerCase();
+  if (!tag) throw new Error('Tags cannot be empty.');
+  if (tag.length > MAX_TAG_LENGTH) {
+    throw new Error(`Tag "${tag}" exceeds the ${MAX_TAG_LENGTH}-character limit.`);
+  }
+  if (!TAG_PATTERN.test(tag)) {
+    throw new Error(`Invalid tag "${tag}". Use only letters, numbers, hyphens, and underscores.`);
+  }
+  return tag;
+}
+
+export function normalizeTags(values, { allowUntagged = false } = {}) {
+  const input = Array.isArray(values)
+    ? values
+    : typeof values === 'string'
+      ? (values.trim() ? values.split(',') : [])
+      : values == null
+        ? []
+        : [values];
+  const tags = [...new Set(input.map(normalizeTag))].sort();
+  if (!allowUntagged && tags.includes(UNTAGGED_FILTER)) {
+    throw new Error(`"${UNTAGGED_FILTER}" is reserved for filtering and cannot be saved as a tag.`);
+  }
+  if (tags.length > MAX_TAGS_PER_MISSION) {
+    throw new Error(`A mission can have at most ${MAX_TAGS_PER_MISSION} tags.`);
+  }
+  return tags;
+}
+
+export function matchesTagFilter(missionTags, requestedTags, match = 'any') {
+  const actual = normalizeTags(missionTags);
+  const requested = normalizeTags(requestedTags, { allowUntagged: true });
+  if (!requested.length) return true;
+  const has = (tag) => tag === UNTAGGED_FILTER ? actual.length === 0 : actual.includes(tag);
+  return match === 'all' ? requested.every(has) : requested.some(has);
+}
+
+export function normalizeTagMatch(value) {
+  const match = String(value ?? 'any').trim().toLowerCase();
+  if (match !== 'any' && match !== 'all') {
+    throw new Error('tagMatch must be "any" or "all".');
+  }
+  return match;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testronaut",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "main": "./runner/testronaut.js",
   "bin": {
     "testronaut": "bin/cli.js"

package/runner/testronaut.js

@@ -28,6 +28,7 @@ import path from 'path';
 import { runAgent } from '../core/agent.js';
 import { redactPasswordInText } from '../core/redaction.js';
 import { loadConfig, enforceTurnBudget, getRetryLimit, getDomListLimit, getResourceGuardConfig, getHumanInputConfig } from '../core/config.js';
+import { normalizeTags } from '../core/tags.js';
 
 // Check process env for debug toggles (shared helper for tests and CLI).
 const isDebugEnabled = () => {
@@ -44,7 +45,7 @@ const formatListLimit = (v) => v === Infinity ? 'all' : v;
  * @param {{ preMission?: any|any[], mission?: any|any[], postMission?: any|any[] }} params
  * @param {string} missionName
  */
-export async function runMissions({ preMission, mission, postMission }, missionName) {
+export async function runMissions({ preMission, mission, postMission, tags = [] }, missionName) {
   // 1) Config and turn budget (with guardrails)
   const cfg = await loadConfig();
   const { effectiveMax, limits, notes } = enforceTurnBudget(cfg);
@@ -55,6 +56,11 @@ export async function runMissions({ preMission, mission, postMission }, missionN
   const resourceGuard = getResourceGuardConfig(cfg);
   const humanInput = getHumanInputConfig(cfg);
   const debugEnabled = isDebugEnabled();
+  const missionTags = normalizeTags([
+    ...normalizeTags(tags),
+    ...normalizeTags(cfg?.addTags),
+    ...normalizeTags(process.env.TESTRONAUT_ADD_TAGS),
+  ]);
   if (notes.length) {
     console.warn(notes.join('\n'));
   }
@@ -208,6 +214,10 @@ export async function runMissions({ preMission, mission, postMission }, missionN
     return;
   }
 
+  for (const result of success) {
+    result.tags = result.submissionType === 'mission' ? missionTags : [];
+  }
+
   const missionStatus = success[0].steps[success[0].steps.length - 1].result;
   if (missionStatus.toLowerCase().includes('failure')) {
     success[0].status = 'failed';

package/tests/binTests/cli.helpers.test.js

@@ -143,6 +143,49 @@ describe('cli helpers', () => {
     expect(res.invalid).toBe(true);
   });
 
+  it('parses tag flags and aliases without leaving mission-like arguments', () => {
+    const { parseTagArgs } = __test__;
+    const res = parseTagArgs([
+      '--tags=smoke,authentication',
+      '--tag-match', 'all',
+      '--add_tags', 'staging',
+      'login.mission.js',
+    ]);
+    expect(res.tags.value).toBe('smoke,authentication');
+    expect(res.tagMatch.value).toBe('all');
+    expect(res.addTags.value).toBe('staging');
+    expect(res.args).toEqual(['login.mission.js']);
+  });
+
+  it('combines repeated singular and plural tag flags', () => {
+    const { parseTagArgs } = __test__;
+    const res = parseTagArgs([
+      '--tag', 'authentication',
+      '--tag=smoke',
+      '--tags', 'checkout, navigation',
+      '--add-tag', 'staging',
+      '--add-tags=nightly,full-test-run',
+    ]);
+    expect(res.tags.value).toBe('authentication,smoke,checkout, navigation');
+    expect(res.addTags.value).toBe('staging,nightly,full-test-run');
+    expect(res.hasUnquotedCommaSpace).toBe(false);
+    expect(res.args).toEqual([]);
+  });
+
+  it('detects the common unquoted comma-space form for a friendly error', () => {
+    const { parseTagArgs } = __test__;
+    const res = parseTagArgs(['--tags', 'authentication,', 'smoke']);
+    expect(res.hasUnquotedCommaSpace).toBe(true);
+    expect(res.args).toEqual(['smoke']);
+  });
+
+  it('records missing values even when another repeated flag is valid', () => {
+    const { parseTagArgs } = __test__;
+    const res = parseTagArgs(['--tag', '--tag', 'smoke']);
+    expect(res.tags.missingValue).toBe(true);
+    expect(res.tags.value).toBe('smoke');
+  });
+
   describe('detectCliName', () => {
     const { detectCliName } = __test__;
 

package/tests/coreTests/tags.test.js

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { matchesTagFilter, normalizeTagMatch, normalizeTags } from '../../core/tags.js';
+
+describe('tag helpers', () => {
+  it('normalizes case, order, and duplicates', () => {
+    expect(normalizeTags(['Smoke', 'authentication', 'smoke'])).toEqual(['authentication', 'smoke']);
+  });
+
+  it('treats omitted and blank optional tag sources as no tags', () => {
+    expect(normalizeTags()).toEqual([]);
+    expect(normalizeTags(null)).toEqual([]);
+    expect(normalizeTags('')).toEqual([]);
+    expect(normalizeTags('   ')).toEqual([]);
+  });
+
+  it('rejects spaces and the reserved untagged value', () => {
+    expect(() => normalizeTags(['human in loop'])).toThrow(/Invalid tag/);
+    expect(() => normalizeTags(['untagged'])).toThrow(/reserved/);
+  });
+
+  it('supports any, all, and untagged matching', () => {
+    expect(matchesTagFilter(['smoke'], ['smoke', 'checkout'], 'any')).toBe(true);
+    expect(matchesTagFilter(['smoke'], ['smoke', 'checkout'], 'all')).toBe(false);
+    expect(matchesTagFilter([], ['untagged'], 'any')).toBe(true);
+  });
+
+  it('defaults tag matching to any', () => {
+    expect(normalizeTagMatch()).toBe('any');
+    expect(() => normalizeTagMatch('some')).toThrow(/any.*all/);
+  });
+});

package/tests/runnerTests/testronaut.test.js

@@ -137,6 +137,41 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
     log.mockRestore();
   });
 
+  it('adds normalized tags only to main mission submissions', async () => {
+    loadConfig.mockResolvedValue({ addTags: ['staging', 'Smoke'] });
+    enforceTurnBudget.mockReturnValue({ effectiveMax: 20, limits: {}, notes: [], strict: false });
+    process.env.TESTRONAUT_ADD_TAGS = 'full-test-run,smoke';
+    runAgent.mockResolvedValue([
+      { submissionType: 'premission', steps: [{ result: 'SUCCESS' }], status: 'passed' },
+      { submissionType: 'mission', steps: [{ result: 'SUCCESS' }], status: 'passed' },
+      { submissionType: 'postmission', steps: [{ result: 'SUCCESS' }], status: 'passed' },
+    ]);
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    const result = await runMissions({ preMission: 'setup', mission: 'test', postMission: 'cleanup', tags: ['authentication'] }, 'Tagged');
+
+    expect(result[0].tags).toEqual([]);
+    expect(result[1].tags).toEqual(['authentication', 'full-test-run', 'smoke', 'staging']);
+    expect(result[2].tags).toEqual([]);
+    log.mockRestore();
+  });
+
+  it('runs an untagged mission when optional additive tags are blank', async () => {
+    loadConfig.mockResolvedValue({ addTags: [] });
+    enforceTurnBudget.mockReturnValue({ effectiveMax: 20, limits: {}, notes: [], strict: false });
+    process.env.TESTRONAUT_ADD_TAGS = '';
+    runAgent.mockResolvedValue([
+      { submissionType: 'mission', steps: [{ result: 'SUCCESS' }], status: 'passed' },
+    ]);
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    const result = await runMissions({ mission: 'untagged mission' }, 'Untagged');
+
+    expect(result[0].tags).toEqual([]);
+    expect(runAgent).toHaveBeenCalledOnce();
+    log.mockRestore();
+  });
+
   it('normalizes single strings and functions into arrays and names missions', async () => {
     loadConfig.mockResolvedValue({});
     enforceTurnBudget.mockReturnValue({

package/tests/toolsTests/generateHtmlReport.test.js

@@ -27,6 +27,7 @@ describe('generateHtmlReport', () => {
           submissionType: 'mission',
           submissionName: 'Main',
           status: 'passed',
+          tags: ['smoke'],
           steps: [
             {
               turn: 0,
@@ -54,6 +55,13 @@ describe('generateHtmlReport', () => {
     expect(html).toContain('Mission A');
     expect(html).toContain('Turn 1 (re-attempt 1/5)');
     expect(html).toContain('⚠️ Turn Issues');
+    expect(html).toContain('data-tag="smoke"');
+    expect(html).toContain('data-tags="smoke"');
+    expect(html).toContain('data-tag="untagged"');
+    expect(html).toContain('id="match-count"');
+    expect(html).toContain('No missions match these tags');
+    expect(html).toContain('Keep missions that do not match visible');
+    expect(html).not.toContain('<div class="pill">LLM:');
   });
 
   it('escapes unsafe text in output', () => {

package/tools/generateHtmlReport.js

@@ -17,6 +17,7 @@
  */
 import fs from 'fs';
 import path from 'path';
+import { normalizeTags } from '../core/tags.js';
 
 /**
  * Render and write a Testronaut run report to disk.
@@ -27,6 +28,7 @@ import path from 'path';
  */
 export function generateHtmlReport(report, outputPath) {
   const { runId, startTime, endTime, missions = [], summary = {}, llm = {} } = report;
+  const reportTags = normalizeTags(report.tags ?? missions.flatMap(m => m.submissionType === 'mission' ? (m.tags ?? []) : []));
   const durationSec =
     (startTime && endTime)
       ? ((new Date(endTime) - new Date(startTime)) / 1000).toFixed(2)
@@ -40,6 +42,16 @@ export function generateHtmlReport(report, outputPath) {
   const badge = (status) =>
     status === 'passed' ? '✅ Passed' :
     status === 'failed' ? '❌ Failed' : (status || '—');
+  const tagPalette = [
+    ['#60a5fa', 'rgba(96,165,250,.18)'], ['#a78bfa', 'rgba(167,139,250,.18)'],
+    ['#34d399', 'rgba(52,211,153,.18)'], ['#f472b6', 'rgba(244,114,182,.18)'],
+    ['#fbbf24', 'rgba(251,191,36,.18)'], ['#22d3ee', 'rgba(34,211,238,.18)'],
+  ];
+  const tagStyle = (tag) => {
+    const index = [...tag].reduce((sum, char) => sum + char.charCodeAt(0), 0) % tagPalette.length;
+    const [color, background] = tagPalette[index];
+    return `color:${color};background:${background};border-color:${color}66`;
+  };
 
   const submissionBlock = (m) => {
     const mDurationSec =
@@ -128,6 +140,7 @@ export function generateHtmlReport(report, outputPath) {
     const firstStart = Math.min(...subs.map(s => s.startTime || 0).filter(Boolean));
     const lastEnd    = Math.max(...subs.map(s => s.endTime || 0).filter(Boolean));
     const groupDur   = (firstStart && lastEnd) ? ((lastEnd - firstStart) / 1000).toFixed(2) : '—';
+    const tags = normalizeTags(subs.flatMap(s => s.submissionType === 'mission' ? (s.tags ?? []) : []));
 
     // pre → mission → post
     const order = { premission: 0, mission: 1, postmission: 2 };
@@ -137,9 +150,10 @@ export function generateHtmlReport(report, outputPath) {
     );
 
     return `
-      <details class="mission-group">
+      <details class="mission-group" data-tags="${esc(tags.join(','))}">
         <summary>
           <span class="name">${esc(missionName)}</span>
+          <span class="mission-tags">${tags.map(tag => `<span class="tag-small" style="${tagStyle(tag)}">${esc(tag)}</span>`).join('')}</span>
           <span class="status ${status === 'failed' ? 'bad' : 'ok'}">${badge(status)}</span>
           <span class="meta">submissions: ${subs.length} • steps: ${totalSteps} • duration: ${groupDur}s</span>
           <span class="toolbar">
@@ -233,6 +247,21 @@ export function generateHtmlReport(report, outputPath) {
     }
     .pill.ok{ background: var(--chip-ok-bg); color: var(--ok); border-color: var(--chip-ok-border); font-weight:700; }
     .pill.bad{ background: var(--chip-bad-bg); color: var(--bad); border-color: var(--chip-bad-border); font-weight:700; }
+    .tag-filter{max-width:928px;margin:0 auto 20px;padding:18px 16px;background:rgba(2,6,23,.30);}
+    .tag-filter-heading{display:flex;align-items:center;gap:7px;margin-bottom:12px;flex-wrap:wrap;}
+    .tag-filter-title{font-size:14px;color:var(--text);font-weight:800;}
+    .info{display:inline-grid;place-items:center;width:17px;height:17px;border:1px solid var(--chip-border);border-radius:50%;font-size:11px;color:var(--text-muted);cursor:help;}
+    .match-count{margin-left:auto;color:var(--text-muted);font-size:12px;}
+    .tag-buttons,.mission-tags{display:flex;gap:6px;flex-wrap:wrap;align-items:center;}
+    .tag-button,.tag-small{border:1px solid var(--chip-border);background:rgba(255,255,255,.06);color:var(--text);border-radius:999px;padding:5px 10px;font-size:11px;font-weight:700;}
+    .tag-button{cursor:pointer;transition:transform .15s ease,background .15s ease}.tag-button:hover{transform:translateY(-1px);background:rgba(255,255,255,.11)}.tag-button.active{box-shadow:0 0 0 2px rgba(96,165,250,.38);}
+    .filter-controls{display:flex;gap:16px;align-items:center;margin-top:14px;font-size:12px;color:var(--text-muted);flex-wrap:wrap;}
+    .filter-controls select{color:var(--text);background:#111a31;border:1px solid var(--chip-border);border-radius:8px;padding:6px 24px 6px 8px;}
+    .show-control{cursor:help;display:flex;align-items:center;gap:5px;}
+    .filter-empty{max-width:928px;margin:12px auto;padding:28px 16px;text-align:center;border:1px dashed var(--hairline-strong);border-radius:16px;color:var(--text-muted);}
+    .filter-empty strong{display:block;color:var(--text);font-size:18px;margin-bottom:6px;}
+    .mission-group.nonmatching{opacity:.45;}
+    @media(max-width:640px){.match-count{width:100%;margin-left:0}.tag-filter{padding:14px 12px}.meta{display:none}}
 
     /* ===== Disclosure blocks ===== */
     details{ background: rgba(255,255,255,.05); border:1px solid var(--hairline); border-radius:16px; margin:10px 0; overflow:hidden; }
@@ -328,14 +357,76 @@ export function generateHtmlReport(report, outputPath) {
     <div class="pill">Missions: ${esc(summary.totalMissions ?? totals.total)}</div>
     <div class="pill ok">Passed: ${esc(summary.passed ?? totals.passed)}</div>
     <div class="pill bad">Failed: ${esc(summary.failed ?? totals.failed)}</div>
-    <div class="pill">LLM: ${esc(llm.provider ?? '—')} • ${esc(llm.model ?? '')}</div>
+  </div>
+
+  <div class="tag-filter glass">
+    <div class="tag-filter-heading">
+      <span class="tag-filter-title">Filter missions by tag</span>
+      <span class="info" title="Select one or more tags to focus the report. Match Any uses OR; Match All requires every selected tag.">i</span>
+      <span class="match-count" id="match-count">${totals.total} of ${totals.total} missions match</span>
+    </div>
+    <div class="tag-buttons">
+      ${reportTags.map(tag => `<button type="button" class="tag-button" data-tag="${esc(tag)}" style="${tagStyle(tag)}">${esc(tag)}</button>`).join('')}
+      <button type="button" class="tag-button" data-tag="untagged">untagged</button>
+    </div>
+    <div class="filter-controls">
+      <label>Match <select id="tag-match"><option value="any">any</option><option value="all">all</option></select></label>
+      <label class="show-control" title="Keep missions that do not match visible in a muted style instead of hiding them."><input id="show-nonmatching" type="checkbox"> Show nonmatching missions <span class="info">i</span></label>
+      <button type="button" id="clear-tags" class="tag-button" hidden>Clear filters</button>
+    </div>
   </div>
 
   <div class="container">
     ${groupsHtml || '<div class="glass empty">No missions recorded.</div>'}
   </div>
+  <div class="filter-empty" id="filter-empty" hidden>
+    <strong>No missions match these tags</strong>
+    Try removing a tag, switching to “Any,” or showing nonmatching missions.
+  </div>
   <script>
   (function () {
+    var selectedTags = [];
+    function applyTagFilter() {
+      var match = document.getElementById('tag-match');
+      var show = document.getElementById('show-nonmatching');
+      var matchedCount = 0;
+      var totalCount = 0;
+      document.querySelectorAll('.mission-group').forEach(function (group) {
+        totalCount += 1;
+        var tags = (group.getAttribute('data-tags') || '').split(',').filter(Boolean);
+        var test = function (tag) { return tag === 'untagged' ? tags.length === 0 : tags.indexOf(tag) >= 0; };
+        var matches = !selectedTags.length || ((match && match.value === 'all') ? selectedTags.every(test) : selectedTags.some(test));
+        if (matches) matchedCount += 1;
+        group.hidden = !matches && !(show && show.checked);
+        group.classList.toggle('nonmatching', !matches);
+      });
+      var count = document.getElementById('match-count');
+      var empty = document.getElementById('filter-empty');
+      var clear = document.getElementById('clear-tags');
+      if (count) count.textContent = matchedCount + ' of ' + totalCount + ' missions match';
+      if (empty) empty.hidden = matchedCount !== 0 || !selectedTags.length || !!(show && show.checked);
+      if (clear) clear.hidden = selectedTags.length === 0;
+    }
+    document.querySelectorAll('.tag-button[data-tag]').forEach(function (button) {
+      button.addEventListener('click', function () {
+        var tag = button.getAttribute('data-tag');
+        var idx = selectedTags.indexOf(tag);
+        if (idx >= 0) selectedTags.splice(idx, 1); else selectedTags.push(tag);
+        button.classList.toggle('active', idx < 0);
+        applyTagFilter();
+      });
+    });
+    var tagMatch = document.getElementById('tag-match');
+    var showNonmatching = document.getElementById('show-nonmatching');
+    var clearTags = document.getElementById('clear-tags');
+    if (tagMatch) tagMatch.addEventListener('change', applyTagFilter);
+    if (showNonmatching) showNonmatching.addEventListener('change', applyTagFilter);
+    if (clearTags) clearTags.addEventListener('click', function () {
+      selectedTags = [];
+      document.querySelectorAll('.tag-button[data-tag]').forEach(function (button) { button.classList.remove('active'); });
+      applyTagFilter();
+    });
+    applyTagFilter();
     function setOpenAll(root, selector, open) {
       root.querySelectorAll(selector).forEach(function (el) {
         if (el && 'open' in el) el.open = open;