testronaut 2.0.2 → 2.1.0

package/TODO.md

@@ -12,6 +12,7 @@
 ## Browser Automation Follow-Ups
 
 - [x] Make `click_text` match exact text, prefer the innermost visible element, and fail quickly instead of clicking an ancestor or partial match.
+- [ ] Replace framework/vendor-specific DOM class stripping with a framework-agnostic classifier that removes generated hashes, styling utilities, variants, and arbitrary selectors while preserving semantic component classes. Reconsider broad prefix rules such as `/^cl-/`, cap retained class count and length, and add representative fixtures for Tailwind, MUI, Ant Design, Chakra, Clerk, CSS Modules, and CSS-in-JS.
 
 ## Session and Reporting Follow-Ups
 

package/bin/cli.js

@@ -107,6 +107,8 @@ const screenshotsEnabled = !args.includes('--no-screenshots');
 args = args.filter(arg => arg !== '--no-screenshots');
 const uploadScreenshots = !args.includes('--no-upload-screenshots');
 args = args.filter(arg => arg !== '--no-upload-screenshots');
+const strictRecoveryFlag = args.includes('--strict-recovery');
+args = args.filter(arg => arg !== '--strict-recovery');
 process.env.TESTRONAUT_SCREENSHOTS = screenshotsEnabled ? '1' : '0';
 
 let sessionMode = 'isolated';
@@ -430,6 +432,11 @@ function buildEffectiveConfig(config = {}, cwd = process.cwd()) {
     tagMatch: config.tagMatch || 'any',
     addTags: normalizeTags([...(config.addTags || []), ...cliAddTags]),
     screenshots: screenshotsEnabled,
+    recovery: {
+      permitted: Array.isArray(config?.recovery?.permitted) ? config.recovery.permitted : null,
+      failBuild: strictRecoveryFlag || config?.recovery?.failBuild === true,
+      source: strictRecoveryFlag ? 'cli' : (config?.recovery?.failBuild != null ? 'config' : 'default'),
+    },
     authenticated: Boolean(config.sessionToken),
     optimization,
     guardrails: {
@@ -487,9 +494,13 @@ function collectReportScreenshotPaths(report) {
   const names = [];
   const seen = new Set();
   for (const mission of Array.isArray(report?.missions) ? report.missions : []) {
-    for (const step of Array.isArray(mission?.steps) ? mission.steps : []) {
-      if (typeof step?.screenshotPath !== 'string') continue;
-      const name = step.screenshotPath.trim().replace(/^\.\//, '').replaceAll('\\', '/');
+    const references = [
+      ...(Array.isArray(mission?.steps) ? mission.steps.map(step => step?.screenshotPath) : []),
+      ...(Array.isArray(mission?.recoveries) ? mission.recoveries.map(recovery => recovery?.screenshot) : []),
+    ];
+    for (const reference of references) {
+      if (typeof reference !== 'string') continue;
+      const name = reference.trim().replace(/^\.\//, '').replaceAll('\\', '/');
       if (!name || seen.has(name)) continue;
       seen.add(name);
       names.push(name);
@@ -888,6 +899,7 @@ Options:
   --dry-run                 Show the resolved mission plan without launching a browser
   --no-screenshots          Remove the screenshot tool for this run
   --no-upload-screenshots   Upload report JSON without its screenshots
+  --strict-recovery         Exit non-zero when any mission passes after recovery
   --json                    Emit machine-readable command/run output
   --quiet                   Suppress informational logs
   --base=<git-ref>          Base ref for Jev suite selection (default: HEAD~1)
@@ -980,6 +992,7 @@ const {
 } = await discoverMissionFiles({ cwd: process.cwd() });
 for (const warning of missionDiscoveryWarnings) console.warn(`⚠️ ${warning}`);
 const tagConfig = await loadConfig(process.cwd());
+const strictRecovery = strictRecoveryFlag || tagConfig?.recovery?.failBuild === true;
 const optimizationPolicy = resolveOptimizationPolicy({ config: tagConfig });
 if (!optimizationPolicy.valid) {
   console.error('❌ Invalid optimization objective or mode in testronaut-config.json.');
@@ -1186,7 +1199,7 @@ const runFile = async (filePath) => {
         durationMs: Math.max(0, missionFileEndTime - missionFileStartTime),
       });
       const missionResults = Array.isArray(result) ? result : [result];
-      return !missionResults.some(item => item?.status === 'failed');
+      return !missionResults.some(item => item?.status === 'failed' || (strictRecovery && item?.status === 'recovered'));
     }
     console.error(`❌ Mission does not export executeMission(): ${filePath}`);
   } catch (err) {
@@ -1256,7 +1269,7 @@ const { provider: llmProvider, model: llmModel } = resolveProviderModel({ cwd: p
 
 
 const report = {
-  schemaVersion: 2,
+  schemaVersion: 3,
   runId,
   cli: { version: CLI_VERSION },
   startTime: startTime.toISOString(),
@@ -1271,6 +1284,7 @@ const report = {
   summary: {
     totalMissions: flatMissions.length,
     passed: flatMissions.filter(m => m.status === 'passed').length,
+    recovered: flatMissions.filter(m => m.status === 'recovered').length,
     failed: flatMissions.filter(m => m.status === 'failed').length,
   },
   missions: flatMissions
@@ -1319,7 +1333,7 @@ fs.writeFileSync(path.join(outputDir, `${runId}.json`), JSON.stringify(report, n
 const htmlReportPath = path.join(outputDir, `${runId}.html`);
 generateHtmlReport(report, htmlReportPath);
 if (jsonOutput) writeOutput(report);
-else terminalUi.summary({ ...report.summary, durationMs: report.durationMs, reportPath: path.relative(process.cwd(), htmlReportPath) });
+else terminalUi.summary({ ...report.summary, strictRecovery, durationMs: report.durationMs, reportPath: path.relative(process.cwd(), htmlReportPath) });
 
   try {
     if (!process.env.TN_KEEP_TMP && fs.existsSync(TMP_DIR)) {

package/bin/terminalUi.js

@@ -6,6 +6,7 @@ const ANSI = {
   cyan: '\u001b[38;5;81m',
   teal: '\u001b[38;5;43m',
   red: '\u001b[38;5;203m',
+  amber: '\u001b[38;5;214m',
   cream: '\u001b[38;5;230m',
 };
 
@@ -44,13 +45,13 @@ export function createTerminalUi({
       const tagText = tags.length ? paint(ANSI.dim, `  ${tags.map(tag => `#${tag}`).join(' ')}`) : '';
       write(`   ${marker} ${file}${tagText}`);
     },
-    summary({ totalMissions = 0, passed = 0, failed = 0, durationMs, reportPath }) {
-      const status = failed === 0
+    summary({ totalMissions = 0, passed = 0, recovered = 0, failed = 0, strictRecovery = false, durationMs, reportPath }) {
+      const status = failed === 0 && !(strictRecovery && recovered > 0)
         ? paint(`${ANSI.bold}${ANSI.teal}`, 'MISSION COMPLETE')
         : paint(`${ANSI.bold}${ANSI.red}`, 'MISSION NEEDS REVIEW');
       write('');
       write(`${label('COMPLETE')}${status}`);
-      write(`   ${paint(ANSI.teal, `${passed} passed`)}  ${paint(failed ? ANSI.red : ANSI.dim, `${failed} failed`)}  ${paint(ANSI.dim, `${totalMissions} total`)}`);
+      write(`   ${paint(ANSI.teal, `${passed} passed`)}  ${paint(recovered ? ANSI.amber : ANSI.dim, `${recovered} recovered`)}  ${paint(failed ? ANSI.red : ANSI.dim, `${failed} failed`)}  ${paint(ANSI.dim, `${totalMissions} total`)}`);
       const duration = formatDuration(durationMs);
       if (duration) write(paint(ANSI.dim, `   Duration: ${duration}`));
       if (reportPath) write(paint(ANSI.dim, `   Report: ${reportPath}`));

package/core/agent.js

@@ -37,8 +37,8 @@ import { hasCompletedLaunchProtocol, markLaunchProtocolCompleted } from './launc
  * @param {string} missionName
  * @param {number} [maxTurns=20] - upper bound for turnLoop per goal
  * @param {number} [retryLimit]
- * @param {{ domListLimit?: number|typeof Infinity, automaticDomLimit?: number, storageStatePath?: string, debug?: boolean, resourceGuard?: { enabled:boolean, hrefIncludes:string[], dataTypes:string[] }, humanInput?: { enabled:boolean, timeoutSeconds:number } }} [opts]
- * @returns {Promise<Array<{missionName:string, submissionType:string, submissionName:string|null, status:'passed'|'failed', steps:any[], startTime:number, endTime:number}>>}
+ * @param {{ domListLimit?: number|typeof Infinity, automaticDomLimit?: number, storageStatePath?: string, debug?: boolean, resourceGuard?: { enabled:boolean, hrefIncludes:string[], dataTypes:string[] }, humanInput?: { enabled:boolean, timeoutSeconds:number }, recovery?: { permitted?: string[] } }} [opts]
+ * @returns {Promise<Array<{missionName:string, submissionType:string, submissionName:string|null, status:'passed'|'recovered'|'failed', steps:any[], startTime:number, endTime:number}>>}
  */
 export async function runAgent(goals, missionName, maxTurns = 20, retryLimit, opts = {}) {
   const browser = new ChromeBrowser({
@@ -61,6 +61,7 @@ export async function runAgent(goals, missionName, maxTurns = 20, retryLimit, op
     for (const goal of goals) {
       const goalStartTime = Date.now();
       const telemetryStart = groundControl.telemetry.length;
+      const recoveryStart = groundControl.recoveries.length;
       const steps = [];
       const stepsArchive = [];
       // Unique-ish JSONL file for this mission’s steps
@@ -220,6 +221,15 @@ Email invitation and magic links:
 - open_email_link enforces the operator-configured emailLinks.allowedHosts policy. If the host is not configured or navigation is blocked, report a graceful FAILURE; do not use the ordinary navigate tool as a workaround.
         `.trim();
 
+      const permittedRecoveries = Array.isArray(opts.recovery?.permitted)
+        ? opts.recovery.permitted.map(value => String(value).trim().toLowerCase()).filter(Boolean)
+        : null;
+      systemContent += `\n\nRecovery reporting:\n- Call record_recovery before or immediately after taking an action a normal user would not know to take in order to continue.\n- Ordinary mission steps and retries of selectors are not recoveries.\n- ${permittedRecoveries === null
+        ? 'This mission has not restricted recovery actions.'
+        : permittedRecoveries.length
+          ? `Only these recovery actions are permitted: ${permittedRecoveries.join(', ')}.`
+          : 'No recovery actions are permitted; recording one will fail the mission.'}`;
+
       if (opts.humanInput?.enabled !== false) {
         systemContent +=
           '\n' +
@@ -294,25 +304,32 @@ Email invitation and magic links:
       const goalEndTime = Date.now();
 
       // Snapshot steps (avoid retaining references to mutable arrays)
+      const recoveries = JSON.parse(JSON.stringify((groundControl.recoveries || []).slice(recoveryStart)));
+      const disallowedRecoveries = permittedRecoveries === null
+        ? []
+        : recoveries.filter(recovery => !permittedRecoveries.includes(recovery.action));
+      const succeeded = Boolean(result?.success) && disallowedRecoveries.length === 0;
       missionResults.push({
         missionName,
         submissionType: goal.submissionType || goal.label,
         submissionName: goal.submissionName || null,
-        status: result?.success ? 'passed' : 'failed',
+        status: succeeded ? (recoveries.length ? 'recovered' : 'passed') : 'failed',
         steps: JSON.parse(JSON.stringify(compact)), // last 20 (by memory design)
         stepFile, // full history is in this JSONL (one step per line)
         startTime: goalStartTime,
         endTime: goalEndTime,
         durationMs: Math.max(0, goalEndTime - goalStartTime),
         telemetry: JSON.parse(JSON.stringify(groundControl.telemetry.slice(telemetryStart))),
+        recoveries,
+        ...(disallowedRecoveries.length ? { recoveryPolicyViolation: disallowedRecoveries.map(item => item.action) } : {}),
         ...(protocolResult ? { launchProtocol: protocolResult } : {}),
       });
 
-      if (protocol && result?.success) {
+      if (protocol && succeeded) {
         markLaunchProtocolCompleted(protocol.id);
       }
 
-      if (!result?.success) {
+      if (!succeeded) {
         console.log('🛑 Agent stopped due to failed goal.\n');
         return missionResults;
       }

package/core/turnLoop.js

@@ -59,6 +59,7 @@ import {
   createEmptyGroundControl,
   applyGroundControlUpdate,
   recordGroundTelemetry,
+  recordRecovery,
  } from '../tools/contextControl.js';
 
 // ─────────────────────────────────────────────
@@ -159,6 +160,7 @@ const TURN_RETRY_BASE_DELAY_MS = 500;
 const FIRE_AND_FORGET_TOOLS = new Set([
   'screenshot',
   'click',
+  'reload',
   'click_text',
   // 'expand_menu',
   'fill',
@@ -170,6 +172,7 @@ const FIRE_AND_FORGET_TOOLS = new Set([
   'request_human_input',
   'set_ground_control_state',
   'record_mission_telemetry',
+  'record_recovery',
 ]);
 
 function currentBrowserUrl(browser) {
@@ -630,6 +633,14 @@ export const turnLoop = async (
           } else if (fnName === 'record_mission_telemetry') {
             const recorded = recordGroundTelemetry(groundControl, args, { turn });
             result = { ok: true, recorded };
+          } else if (fnName === 'record_recovery') {
+            let screenshot = null;
+            if (args.screenshot && process.env.TESTRONAUT_SCREENSHOTS !== '0') {
+              const screenshotResult = await CHROME_TOOL_MAP.screenshot(browser, {}, agentMemory);
+              screenshot = String(screenshotResult || '').match(/(?:\.\/)?screenshots\/[^\s]+/)?.[0] || null;
+            }
+            const recorded = recordRecovery(groundControl, args, { turn, screenshot });
+            result = { ok: true, recorded };
           } else {
             const toolHandler = CHROME_TOOL_MAP[fnName];
             if (typeof toolHandler !== 'function') throw new Error(`Unknown tool: ${fnName}`);
@@ -973,7 +984,7 @@ export const turnLoop = async (
         // model functionCall to immediately follow user content or a
         // functionResponse; inserting it before `msg` would create adjacent,
         // reversed model function-call turns.
-        if (!errorMessage && ['click_text', 'click', 'expand_menu'].includes(fnName)) {
+        if (!errorMessage && ['click_text', 'click', 'expand_menu', 'reload'].includes(fnName)) {
           domRefreshSource = fnName;
         }
       }

package/package.json

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

package/runner/testronaut.js

@@ -50,7 +50,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, tags = [] }, missionName) {
+export async function runMissions({ preMission, mission, postMission, tags = [], recovery }, missionName) {
   // 1) Config and turn budget (with guardrails)
   const cfg = await loadConfig();
   const { effectiveMax, limits, notes } = enforceTurnBudget(cfg);
@@ -61,6 +61,7 @@ export async function runMissions({ preMission, mission, postMission, tags = []
   const automaticDomLimitInfo = getAutomaticDomLimit(cfg);
   const resourceGuard = getResourceGuardConfig(cfg);
   const humanInput = getHumanInputConfig(cfg);
+  const recoveryPolicy = recovery ?? cfg?.recovery;
   const debugEnabled = isDebugEnabled();
   const missionTags = normalizeTags([
     ...normalizeTags(tags),
@@ -226,6 +227,7 @@ export async function runMissions({ preMission, mission, postMission, tags = []
       debug: debugEnabled,
       resourceGuard,
       humanInput,
+      recovery: recoveryPolicy,
     }
   );
   if (!success) {

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

@@ -100,10 +100,10 @@ describe('cli helpers', () => {
     const { collectReportScreenshotNames, collectReportScreenshotPaths } = __test__;
     const report = { missions: [
       { steps: [{ screenshotPath: './screenshots/one.png' }, { screenshotPath: './screenshots/two.jpg' }] },
-      { steps: [{ screenshotPath: './screenshots/one.png' }, { events: [] }] },
+      { steps: [{ screenshotPath: './screenshots/one.png' }, { events: [] }], recoveries: [{ screenshot: './screenshots/recovery.png' }] },
     ] };
-    expect(collectReportScreenshotNames(report)).toEqual(['one.png', 'two.jpg']);
-    expect(collectReportScreenshotPaths(report)).toEqual(['screenshots/one.png', 'screenshots/two.jpg']);
+    expect(collectReportScreenshotNames(report)).toEqual(['one.png', 'two.jpg', 'recovery.png']);
+    expect(collectReportScreenshotPaths(report)).toEqual(['screenshots/one.png', 'screenshots/two.jpg', 'screenshots/recovery.png']);
   });
 
   it('preserves run-specific screenshot paths', () => {

package/tests/binTests/terminalUi.test.js

@@ -17,12 +17,13 @@ describe('terminal UI', () => {
     ui.banner({ version: '1.2.3', provider: 'openai', model: 'gpt-test', session: 'isolated' });
     ui.phase('launch', 'login.mission.js');
     ui.mission(true, 'login.mission.js', ['smoke']);
-    ui.summary({ totalMissions: 1, passed: 1, failed: 0, durationMs: 1234, reportPath: 'reports/run.html' });
+    ui.summary({ totalMissions: 2, passed: 1, recovered: 1, failed: 0, durationMs: 1234, reportPath: 'reports/run.html' });
 
     expect(target.read()).toContain('🧑‍🚀 TESTRONAUT  /  MISSION RUNNER');
     expect(target.read()).toContain('LAUNCH    login.mission.js');
     expect(target.read()).toContain('#smoke');
     expect(target.read()).toContain('MISSION COMPLETE');
+    expect(target.read()).toContain('1 recovered');
     expect(target.read()).toContain('Duration: 1.23s');
     expect(target.read()).not.toContain('\u001b[');
   });

package/tests/coreTests/agent.test.js

@@ -119,6 +119,24 @@ describe('core/agent.runAgent', () => {
     expect(result.telemetry).toEqual([{ kind: 'note', text: 'durable observation' }]);
   });
 
+  it('marks a successful goal recovered and enforces permitted actions', async () => {
+    turnLoop.mockImplementationOnce(async (browser, messages, maxTurns, ct, rc, cs, ctx) => {
+      ctx.groundControl.recoveries.push({ turn: 2, action: 'reload', reason: 'message was missing' });
+      return { success: true };
+    });
+    const [recovered] = await runAgent([{ goal: 'Observe' }], 'Recovery', 3, 2, { recovery: { permitted: ['reload'] } });
+    expect(recovered.status).toBe('recovered');
+    expect(recovered.recoveries).toEqual([{ turn: 2, action: 'reload', reason: 'message was missing' }]);
+
+    turnLoop.mockImplementationOnce(async (browser, messages, maxTurns, ct, rc, cs, ctx) => {
+      ctx.groundControl.recoveries.push({ turn: 1, action: 'resend', reason: 'submission disappeared' });
+      return { success: true };
+    });
+    const [failed] = await runAgent([{ goal: 'Observe' }], 'Recovery', 3, 2, { recovery: { permitted: ['reload'] } });
+    expect(failed.status).toBe('failed');
+    expect(failed.recoveryPolicyViolation).toEqual(['resend']);
+  });
+
   it('reuses a completed launch protocol after a passing shared-auth probe', async () => {
     process.env.TESTRONAUT_SESSION_MODE = 'shared-auth';
     const probeSpy = vi.spyOn(ChromeBrowser.prototype, 'probe').mockResolvedValue({

package/tests/runnerTests/testronaut.test.js

@@ -67,6 +67,18 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
     log.mockRestore();
   });
 
+  it('uses project recovery policy unless the mission overrides it', async () => {
+    loadConfig.mockResolvedValue({ maxTurns: 20, recovery: { permitted: ['reload'] } });
+    enforceTurnBudget.mockReturnValue({ effectiveMax: 20, limits: {}, notes: [] });
+    runAgent.mockResolvedValue([{ steps: [{ result: 'SUCCESS' }], status: 'passed' }]);
+
+    await runMissions({ mission: 'Check dashboard' }, 'Configured recovery');
+    expect(runAgent.mock.calls[0][4].recovery).toEqual({ permitted: ['reload'] });
+
+    await runMissions({ mission: 'Check dashboard', recovery: { permitted: [] } }, 'No recovery');
+    expect(runAgent.mock.calls[1][4].recovery).toEqual({ permitted: [] });
+  });
+
   it('unwraps launch protocols while preserving preMission authoring', async () => {
     loadConfig.mockResolvedValue({ maxTurns: 20 });
     enforceTurnBudget.mockReturnValue({

package/tests/toolsTests/chromeBrowserClickText.test.js

@@ -42,3 +42,31 @@ describe('ChromeBrowser.click_text', () => {
     expect(browser.page.getByText).toHaveBeenCalledWith('Add', { exact: true });
   });
 });
+
+describe('ChromeBrowser.check_text', () => {
+  it('reports text when at least one matching element is visible', async () => {
+    const matches = {
+      count: vi.fn().mockResolvedValue(2),
+      nth: vi.fn(index => [
+        { isVisible: vi.fn().mockResolvedValue(false) },
+        { isVisible: vi.fn().mockResolvedValue(true) },
+      ][index]),
+    };
+    const browser = Object.create(ChromeBrowser.prototype);
+    browser.page = { getByText: vi.fn().mockReturnValue(matches) };
+
+    await expect(browser.check_text({ text: 'Signed out' })).resolves.toBe('FOUND: Signed out');
+    expect(browser.page.getByText).toHaveBeenCalledWith('Signed out');
+  });
+
+  it('does not report text that only exists in hidden elements', async () => {
+    const matches = {
+      count: vi.fn().mockResolvedValue(1),
+      nth: vi.fn().mockReturnValue({ isVisible: vi.fn().mockResolvedValue(false) }),
+    };
+    const browser = Object.create(ChromeBrowser.prototype);
+    browser.page = { getByText: vi.fn().mockReturnValue(matches) };
+
+    await expect(browser.check_text({ text: 'Hidden message' })).resolves.toBe('NOT FOUND: Hidden message');
+  });
+});

package/tests/toolsTests/contextControl.test.js

@@ -27,9 +27,20 @@ import {
   createEmptyGroundControl,
   applyGroundControlUpdate,
   recordGroundTelemetry,
+  recordRecovery,
   summarizeGroundControlForPrompt
 } from '../../tools/contextControl.js';
 
+describe('recordRecovery', () => {
+  it('normalizes and records structured recovery evidence', () => {
+    const groundControl = createEmptyGroundControl();
+    expect(recordRecovery(groundControl, { action: ' Reload ', reason: 'Message missing', evidence: 'Appeared later' }, { turn: 3, screenshot: './screenshots/recovery.png' })).toEqual({
+      turn: 3, action: 'reload', reason: 'Message missing', evidence: 'Appeared later', screenshot: './screenshots/recovery.png',
+    });
+    expect(groundControl.recoveries).toHaveLength(1);
+  });
+});
+
 describe('sanitizeHeavyToolHistory', () => {
   it('stubs older get_dom tool messages but keeps the latest N intact', () => {
     const messages = [

package/tests/toolsTests/domControl.test.js

@@ -285,7 +285,7 @@ describe('domControl helpers', () => {
       const html = `
         <button
           id="btn"
-          class="text-sm bg-red-500 hover:bg-red-600 flex items-center btn-primary custom-class"
+          class="text-sm bg-red-500 hover:bg-red-600 disabled:opacity-50 [&amp;_svg]:size-4 flex items-center btn-primary custom-class"
         >
           Click
         </button>
@@ -301,6 +301,8 @@ describe('domControl helpers', () => {
       expect(classes).not.toContain('text-sm');
       expect(classes).not.toContain('bg-red-500');
       expect(classes).not.toContain('hover:bg-red-600');
+      expect(classes).not.toContain('disabled:opacity-50');
+      expect(classes).not.toContain('[&_svg]:size-4');
       expect(classes).not.toContain('flex');
       expect(classes).not.toContain('items-center');
 

package/tests/toolsTests/generateHtmlReport.test.js

@@ -18,6 +18,17 @@ afterEach(() => {
 });
 
 describe('generateHtmlReport', () => {
+  it('renders recovered status and recovery evidence', () => {
+    const outPath = path.join(tmpDir, 'recovered.html');
+    generateHtmlReport({ summary: { passed: 0, recovered: 1, failed: 0 }, missions: [{
+      missionName: 'Chat', status: 'recovered', recoveries: [{ turn: 1, action: 'reload', reason: 'message missing', screenshot: './screenshots/recovery.png' }], steps: [],
+    }] }, outPath);
+    const html = fs.readFileSync(outPath, 'utf8');
+    expect(html).toContain('Passed after recovery');
+    expect(html).toContain('Recovered: 1');
+    expect(html).toContain('message missing');
+    expect(html).toContain('./screenshots/recovery.png');
+  });
   it('points local reports to hosted analytics for the same run', () => {
     const report = { runId: 'run_analytics_123', missions: [] };
     const outPath = path.join(tmpDir, 'analytics-cta.html');

package/tests/toolsTests/toolSchema.test.js

@@ -6,6 +6,17 @@ describe('tools/toolSchema', () => {
     expect(toolsSchema.map(tool => tool.function.name)).not.toContain('get_dom_chunk');
   });
 
+  it('exposes structured recovery recording', () => {
+    const entry = toolsSchema.find(tool => tool.function.name === 'record_recovery');
+    expect(entry.function.parameters.required).toEqual(['action', 'reason']);
+    expect(entry.function.parameters.properties).toHaveProperty('screenshot');
+  });
+
+  it('exposes reload as a first-class browser action', () => {
+    const entry = toolsSchema.find(tool => tool.function.name === 'reload');
+    expect(entry.function.parameters).toEqual({ type: 'object', properties: {}, additionalProperties: false });
+  });
+
   it('allows get_dom calls to be scoped by selector', () => {
     const entry = toolsSchema.find(tool => tool.function.name === 'get_dom');
     expect(entry.function.parameters.properties.selector.type).toBe('string');

package/tools/chromeBrowser.js

@@ -641,6 +641,13 @@ export class ChromeBrowser {
     return `navigated to ${this.page.url()}`;
   }
 
+  async reload() {
+    await this.page.reload({ timeout: 30_000, waitUntil: 'domcontentloaded' });
+    await this.page.waitForLoadState('domcontentloaded').catch(() => {});
+    try { await this._waitLoaderGone(); } catch {}
+    return `reloaded ${this.page.url()}`;
+  }
+
   async probe({ url, selector, text, timeout = 5000 } = {}) {
     if (url) {
       await this.page.goto(url, { timeout: 30_000, waitUntil: 'domcontentloaded' });
@@ -1135,8 +1142,14 @@ export class ChromeBrowser {
 
   
   async check_text({ text }) {
-    const html = await this.page.content();
-    return html.includes(text) ? `FOUND: ${text}` : `NOT FOUND: ${text}`;
+    const matches = this.page.getByText(text);
+    const count = await matches.count();
+    for (let index = 0; index < count; index++) {
+      if (await matches.nth(index).isVisible().catch(() => false)) {
+        return `FOUND: ${text}`;
+      }
+    }
+    return `NOT FOUND: ${text}`;
   }
 
   async click_text({ text, timeout = 3000 }) {
@@ -1439,6 +1452,7 @@ export class ChromeBrowser {
 
 export const CHROME_TOOL_MAP = {
   navigate: (b, args) => b.navigate(args),
+  reload: (b) => b.reload(),
   fill: (b, args) => b.fill(args),
   click: (b, args) => b.click(args),
   get_dom: (b, args, agentMemory) => b.get_dom(args, agentMemory),

package/tools/contextControl.js

@@ -140,9 +140,27 @@ export function createEmptyGroundControl() {
       stayWithinBaseUrl: null, // if true, avoid leaving app.baseUrl unless told to
     },
     telemetry: [],             // array of { kind, text, status, ts, turn? }
+    recoveries: [],            // array of { turn, action, reason, evidence?, screenshot? }
   };
 }
 
+export function recordRecovery(groundControl, entry, meta = {}) {
+  if (!groundControl) throw new Error('recordRecovery called without Ground Control state');
+  groundControl.recoveries ||= [];
+  const action = String(entry?.action || '').trim().toLowerCase();
+  const reason = String(entry?.reason || '').trim();
+  if (!action || !reason) return null;
+  const recovery = {
+    turn: meta.turn,
+    action,
+    reason,
+    ...(entry?.evidence ? { evidence: String(entry.evidence).trim() } : {}),
+    ...(meta.screenshot ? { screenshot: meta.screenshot } : {}),
+  };
+  groundControl.recoveries.push(recovery);
+  return recovery;
+}
+
 /**
  * Apply a partial update from the `set_ground_control_state` tool to the
  * existing Ground Control state.

package/tools/domControl.js

@@ -271,7 +271,8 @@ export function removeAutoGeneratedClasses($) {
     const $el = $(el);
     const classes = ($el.attr('class') || '').split(/\s+/);
     const filtered = classes.filter(cls => {
-      return !utilityClassPatterns.some(pattern => pattern.test(cls));
+      const isVariantOrArbitraryUtility = cls.includes(':') || cls.includes('[');
+      return !isVariantOrArbitraryUtility && !utilityClassPatterns.some(pattern => pattern.test(cls));
     });
     if (filtered.length) {
       $el.attr('class', filtered.join(' '));

package/tools/generateHtmlReport.js

@@ -43,6 +43,7 @@ export function generateHtmlReport(report, outputPath) {
     .replace(/"/g, '"');
   const badge = (status) =>
     status === 'passed' ? '✅ Passed' :
+    status === 'recovered' ? '⚠️ Passed after recovery' :
     status === 'failed' ? '❌ Failed' : (status || '—');
   const providerKey = String(llm.provider ?? '').trim().toLowerCase() === 'claude'
     ? 'anthropic'
@@ -160,7 +161,13 @@ export function generateHtmlReport(report, outputPath) {
     const type = String(m.submissionType || 'mission').toLowerCase();
     const typeLabel = (type === 'premission' || type === 'postmission') ? type : 'mission';
     const prettyTitle = `${esc(m.missionName || 'Mission')} — ${typeLabel}${m.submissionName ? `: ${esc(m.submissionName)}` : ''}`;
-    const statusClass = m.status === 'failed' ? 'bad' : (m.status === 'passed' ? 'ok' : '');
+    const statusClass = m.status === 'failed' ? 'bad' : (m.status === 'recovered' ? 'warn' : (m.status === 'passed' ? 'ok' : ''));
+    const recoveries = Array.isArray(m.recoveries) ? m.recoveries : [];
+    const recoveryItems = recoveries.length ? `
+      <div class="recoveries">
+        <h4>Recoveries</h4>
+        ${recoveries.map(recovery => `<div class="recovery"><strong>Turn ${esc(Number(recovery.turn ?? 0) + 1)} · ${esc(recovery.action)}</strong><span>${esc(recovery.reason)}</span>${recovery.evidence ? `<span>${esc(recovery.evidence)}</span>` : ''}${recovery.screenshot ? `<img src="${esc(recovery.screenshot)}" alt="Recovery evidence">` : ''}</div>`).join('')}
+      </div>` : '';
 
     return `
       <details class="mission-submission">
@@ -173,6 +180,7 @@ export function generateHtmlReport(report, outputPath) {
           </span>
         </summary>
         <div class="steps">
+          ${recoveryItems}
           ${stepItems || '<div class="empty">No steps recorded.</div>'}
         </div>
       </details>
@@ -186,7 +194,9 @@ export function generateHtmlReport(report, outputPath) {
     return acc;
   }, {});
 
-  const groupStatus = (subs) => subs.some(s => s.status === 'failed') ? 'failed' : 'passed';
+  const groupStatus = (subs) => subs.some(s => s.status === 'failed')
+    ? 'failed'
+    : subs.some(s => s.status === 'recovered') ? 'recovered' : 'passed';
 
   const missionGroupBlock = (missionName, subs) => {
     const status = groupStatus(subs);
@@ -213,7 +223,7 @@ export function generateHtmlReport(report, outputPath) {
         <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="status ${status === 'failed' ? 'bad' : status === 'recovered' ? 'warn' : 'ok'}">${badge(status)}</span>
           <span class="meta">${sourceFiles.length ? `${sourceFiles.map(esc).join(', ')} • ` : ''}submissions: ${subs.length} • steps: ${totalSteps} • duration: ${groupDur}s • ${esc(tokenMeta(groupModelUsage, groupJevUsage))}</span>
           <span class="toolbar">
             <button class="btn-mini toggle" data-scope="mission" aria-label="Expand">▼</button>
@@ -234,9 +244,10 @@ export function generateHtmlReport(report, outputPath) {
     const st = groupStatus(grouped[name]);
     acc.total += 1;
     acc.passed += st === 'passed' ? 1 : 0;
+    acc.recovered += st === 'recovered' ? 1 : 0;
     acc.failed += st === 'failed' ? 1 : 0;
     return acc;
-  }, { total: 0, passed: 0, failed: 0 });
+  }, { total: 0, passed: 0, recovered: 0, failed: 0 });
 
   const html = `<!DOCTYPE html>
 <html>
@@ -379,9 +390,14 @@ export function generateHtmlReport(report, outputPath) {
     .name{ flex:1; }
     .status.ok{ color: var(--ok); font-weight:700; }
     .status.bad{ color: var(--bad); font-weight:700; }
+    .status.warn{ color: var(--amber); font-weight:700; }
     .meta{ color: var(--text-muted); font-size:12px; }
 
     .steps{ padding: 0 12px 12px; }
+    .recoveries{ margin:12px 0; padding:12px; border:1px solid rgba(251,191,36,.4); border-radius:12px; background:rgba(251,191,36,.1); }
+    .recoveries h4{ margin:0 0 8px; color:var(--amber); }
+    .recovery{ display:grid; gap:4px; margin-top:8px; color:var(--text-muted); }
+    .recovery strong{ color:var(--text); }
     .step summary{
       background: rgba(255,255,255,.04);
       border:1px solid var(--hairline);
@@ -497,6 +513,7 @@ export function generateHtmlReport(report, outputPath) {
   <div class="summary">
     <div class="pill">Missions: ${esc(summary.totalMissions ?? totals.total)}</div>
     <div class="pill ok">Passed: ${esc(summary.passed ?? totals.passed)}</div>
+    <div class="pill warn">Recovered: ${esc(summary.recovered ?? totals.recovered)}</div>
     <div class="pill bad">Failed: ${esc(summary.failed ?? totals.failed)}</div>
     ${optimization?.configured ? `<div class="pill">Optimization: ${esc(optimization.objective)} (${esc(optimization.mode)})</div>` : ''}
     ${Object.entries(reportModelUsage.byModel).length > 1

package/tools/toolSchema.js

@@ -26,6 +26,14 @@ const toolsSchema = [
       },
     },
   },
+  {
+    type: 'function',
+    function: {
+      name: 'reload',
+      description: 'Reload the current page. When reload is used to recover from an unexpected state, also call record_recovery with action "reload".',
+      parameters: { type: 'object', properties: {}, additionalProperties: false },
+    },
+  },
   {
     type: 'function',
     function: {
@@ -95,7 +103,7 @@ const toolsSchema = [
     type: 'function',
     function: {
       name: 'check_text',
-      description: 'Search page HTML for specific text',
+      description: 'Search the page for specific visible text',
       parameters: {
         type: 'object',
         properties: {
@@ -528,6 +536,24 @@ const toolsSchema = [
       }
     }
   },
+  {
+    type: 'function',
+    function: {
+      name: 'record_recovery',
+      description: 'Record a deviation from the normal user journey that was needed to continue, such as reloading, resending, or dismissing an unexpected dialog.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', description: 'Short stable action name, for example "reload", "resend", or "dismiss_dialog".' },
+          reason: { type: 'string', description: 'Why the recovery was necessary and what was observed before it.' },
+          evidence: { type: 'string', description: 'Optional short supporting observation.' },
+          screenshot: { type: 'boolean', description: 'Capture and attach a screenshot at the time the recovery is recorded.' },
+        },
+        required: ['action', 'reason'],
+        additionalProperties: false,
+      }
+    }
+  },
   {
     type: 'function',
     function: {