testronaut 1.3.0 → 1.3.1

package/bin/cli.js

@@ -29,7 +29,7 @@
  * Test strategy:
  *   To test pure helpers without running the whole CLI, we export a tiny test bundle:
  *     export const __test__ = { guessMimeType, safeJoin, findLatestReportPair, pkgManagerForCwd }
- *   See tests in tests/cliTests/cli.helpers.test.js
+ *   See tests in tests/toolsTests/cli.helpers.test.js
  */
 
 import fs from 'fs';
@@ -60,6 +60,11 @@ const apiBase = 'http://api.testronaut.app'; // Replace with your actual API bas
 
 const args = process.argv.slice(2);
 
+/**
+ * Read a JSONL steps file into an array of objects.
+ * @param {string} p
+ * @returns {object[]|null}
+ */
 function readJsonlSteps(p) {
   if (!p || !fs.existsSync(p)) return null;
   const lines = fs.readFileSync(p, 'utf8').split(/\r?\n/).filter(Boolean);
@@ -73,21 +78,27 @@ function readJsonlSteps(p) {
 /**
  * Merge duplicate turns without losing information.
  * Strategy:
- *  - Keep the latest **non-empty** version for a given turn if both exist
+ *  - Keep the latest **non-empty** version for a given (turn,retry) pair
  *  - If both are non-empty, keep the later one (last write wins)
  *  - Preserve original order by line index as a tiebreaker
+ *
+ * @param {Array} steps
+ * @returns {Array}
  */
 function mergeDuplicateTurns(steps) {
   const out = [];
-  const byTurn = new Map(); // turn -> index in out
+  const byKey = new Map(); // composite key -> index in out
   for (const s of steps) {
     const turn = Number.isFinite(s.turn) ? s.turn : out.length;
+    const attempt = Number.isFinite(s.retryAttempt) ? s.retryAttempt : 1;
     const hasEvents = Array.isArray(s.events) && s.events.length > 0;
-    if (!byTurn.has(turn)) {
+    const key = `${turn}::${attempt}`;
+
+    if (!byKey.has(key)) {
       out.push(s);
-      byTurn.set(turn, out.length - 1);
+      byKey.set(key, out.length - 1);
     } else {
-      const idx = byTurn.get(turn);
+      const idx = byKey.get(key);
       const existing = out[idx];
       const existingHasEvents = Array.isArray(existing.events) && existing.events.length > 0;
       // Prefer the one with events; if both have events, prefer the newer (s)
@@ -101,11 +112,28 @@ function mergeDuplicateTurns(steps) {
       }
     }
   }
-  // stable sort by `turn` ascending, then by original order via array index already preserved
-  out.sort((a, b) => (a.turn ?? 0) - (b.turn ?? 0));
+  // stable sort by `turn` then `retryAttempt`, then by original order
+  out.sort((a, b) => {
+    const ta = a.turn ?? 0;
+    const tb = b.turn ?? 0;
+    if (ta !== tb) return ta - tb;
+    const ra = Number.isFinite(a.retryAttempt) ? a.retryAttempt : 1;
+    const rb = Number.isFinite(b.retryAttempt) ? b.retryAttempt : 1;
+    if (ra !== rb) return ra - rb;
+    return 0;
+  });
   return out;
 }
 
+// Expose a small bundle for unit tests (helper-only; not the CLI flow)
+export const __test__ = {
+  guessMimeType,
+  safeJoin,
+  findLatestReportPair,
+  mergeDuplicateTurns,
+  readJsonlSteps,
+};
+
 // Look for --model=<id> or --model <id>
 let modelOverride;
 const modelFlagIndex = args.findIndex(a => a === '--model' || a.startsWith('--model='));
@@ -149,6 +177,37 @@ if (turnsFlagIndex >= 0) {
   args.splice(turnsFlagIndex, turnsOverride ? 2 : 1);
 }
 
+// Look for --retry_limit / --retry-limit
+let retryOverride;
+const retryFlagIndex = args.findIndex(a =>
+  a === '--retry_limit' ||
+  a.startsWith('--retry_limit=') ||
+  a === '--retry-limit' ||
+  a.startsWith('--retry-limit=')
+);
+if (retryFlagIndex >= 0) {
+  const rawArg = args[retryFlagIndex];
+  if (rawArg.includes('=')) {
+    retryOverride = rawArg.split('=')[1];
+  } else if (args[retryFlagIndex + 1]) {
+    retryOverride = args[retryFlagIndex + 1];
+  }
+
+  if (retryOverride) {
+    const n = Number(retryOverride.trim());
+    if (Number.isFinite(n)) {
+      const clamped = Math.min(10, Math.max(1, n));
+      process.env.TESTRONAUT_RETRY_LIMIT = String(clamped);
+      console.log(`🔁 Retry limit override: ${process.env.TESTRONAUT_RETRY_LIMIT} (allowed 1-10)`);
+    } else {
+      console.warn(`⚠️ Invalid --retry_limit value "${retryOverride}". Ignoring.`);
+    }
+  }
+
+  // Remove flag & value so they aren’t treated as filenames
+  args.splice(retryFlagIndex, retryOverride ? 2 : 1);
+}
+
 const missionsDir = path.resolve(process.cwd(), 'missions');
 
 const allResults = [];
@@ -170,6 +229,7 @@ Options:
   --init                    Scaffold project folders and a welcome mission
   --turns=<n>               Override max turns for this run (e.g., --turns=30)
   --help                    Show this help message
+  --retry_limit=<n>         Override agent turn retry limits (minimum 1, maximum 10)
 
 Examples:
   npx testronaut
@@ -720,6 +780,11 @@ function safeJoin(root, relUrlPath) {
   return resolved;
 }
 
+/**
+ * Best-effort cross-platform URL opener.
+ * @param {string} targetUrl
+ * @returns {Promise<void>}
+ */
 async function openInBrowser(targetUrl) {
   const platform = process.platform;
   const quoted = `"${targetUrl}"`;
@@ -848,4 +913,4 @@ try {
   }
 } catch (err) {
   console.warn(`⚠️ Could not remove tmp folder: ${err.message}`);
-}
+}

package/core/agent.js

@@ -37,7 +37,7 @@ import path from 'path';
  * @param {number} [maxTurns=20] - upper bound for turnLoop per goal
  * @returns {Promise<Array<{missionName:string, submissionType:string, submissionName:string|null, status:'passed'|'failed', steps:any[], startTime:number, endTime:number}>>}
  */
-export async function runAgent(goals, missionName, maxTurns = 20) {
+export async function runAgent(goals, missionName, maxTurns = 20, retryLimit) {
   const browser = new ChromeBrowser();
   await browser.start();
   let result;
@@ -52,6 +52,7 @@ export async function runAgent(goals, missionName, maxTurns = 20) {
 
     for (const goal of goals) {
       const steps = [];
+      const stepsArchive = [];
       // Unique-ish JSONL file for this mission’s steps
       const stepFile = path.join(
         tmpDir,
@@ -152,7 +153,9 @@ Use Ground Control as your persistent mission memory about:
         null, // currentStep
         {
           steps,
+          stepsArchive,
           missionName,
+          retryLimit,
           groundControl,
           onStep: (s) => {
             // Append each step as a JSON line
@@ -160,26 +163,24 @@ Use Ground Control as your persistent mission memory about:
               fs.appendFileSync(stepFile, JSON.stringify(s) + '\n');
               // Keep memory in check: retain only the last ~20 steps in RAM
               if (steps.length > 20) steps.splice(0, steps.length - 20);
+              stepsArchive.push(s);
             } catch {} // best-effort; don’t crash the agent
           }
         }
       );
 
       function dedupeSteps(steps) {
-        const seen = new Set();
-        const out = [];
-        for (const s of steps) {
-          const first = s?.events?.[0] || '';
-          const key = `${s.turn}::${s.summary}::${first}`;
-          if (!seen.has(key)) {
-            seen.add(key);
-            out.push(s);
+        const copy = [...steps];
+        copy.sort((a, b) => {
+          if (Number.isFinite(a?._seq) && Number.isFinite(b?._seq)) {
+            return a._seq - b._seq;
           }
-        }
-        return out;
+          return (a?.turn ?? 0) - (b?.turn ?? 0);
+        });
+        return copy;
       }
 
-      const compact = dedupeSteps(steps);
+      const compact = dedupeSteps(stepsArchive.length ? stepsArchive : steps);
 
       // Snapshot steps (avoid retaining references to mutable arrays)
       missionResults.push({

package/core/config.js

@@ -52,6 +52,36 @@ export function getMaxTurns(cfg, fallback = 20) {
   return n;
 }
 
+/**
+ * Resolve retry limit per turn (attempts - 1) with clamping.
+ * Priority: env TESTRONAUT_RETRY_LIMIT → config.retryLimit → fallback
+ *
+ * @param {object} cfg
+ * @param {number} [fallback=2]
+ * @returns {{ value:number, source:'env'|'config'|'default', clamped:boolean }}
+ */
+export function getRetryLimit(cfg, fallback = 2) {
+  const clampRetry = (n) => {
+    const clamped = Math.min(10, Math.max(1, n));
+    return { value: clamped, clamped: clamped !== n };
+  };
+
+  const envVal = Number(process.env.TESTRONAUT_RETRY_LIMIT);
+  if (Number.isFinite(envVal)) {
+    const { value, clamped } = clampRetry(envVal);
+    return { value, source: 'env', clamped };
+  }
+
+  const cfgVal = Number(cfg?.retryLimit);
+  if (Number.isFinite(cfgVal)) {
+    const { value, clamped } = clampRetry(cfgVal);
+    return { value, source: 'config', clamped };
+  }
+
+  const { value, clamped } = clampRetry(fallback);
+  return { value, source: 'default', clamped };
+}
+
 /**
  * Baseline limits for mission runs. Adjust here for global defaults.
  *

package/core/turnLoop.js

@@ -67,6 +67,8 @@ const llm = getLLM(PROVIDER_ID);
 let totalTokensUsed = 0;
 let turnTimestamps = [];
 let shouldBackoff;
+const DEFAULT_TURN_RETRY_LIMIT = 2; // number of retries (not counting initial attempt)
+const TURN_RETRY_BASE_DELAY_MS = 500;
 
 // Certain tools mutate the browser or produce side effects that are
 // *useful for humans* (reports/screenshots), but do not carry semantic
@@ -171,16 +173,25 @@ export const turnLoop = async (
   currentStep = {},
   ctx = {} // { steps, missionName, groundControl }
 ) => {
-  const { steps = [], missionName, groundControl = createEmptyGroundControl() } = ctx;
+  const { steps = [], missionName, groundControl = createEmptyGroundControl(), retryLimit: retryLimitRaw } = ctx;
+  const stepsArchive = ctx.stepsArchive || steps;
+  const retryLimitClamped = Math.min(10, Math.max(1, Number.isFinite(retryLimitRaw) ? retryLimitRaw : DEFAULT_TURN_RETRY_LIMIT)); // retries allowed (excludes initial)
+  const maxAttempts = retryLimitClamped + 1; // includes initial attempt
   ctx.groundControl = groundControl;
   let agentMemory = { lastMenuExpanded: false };
+  let turnRetries = 0;
+  let stepSeq = ctx._stepSeq || 0;
   
   // Centralized recorder: push to in-memory buffer AND fire optional callback for streaming
   // Idempotent recorder – prevents accidental double-push
   const recordStep = (step) => {
     if (!step || step.__recorded) return;
+    step._seq = stepSeq++;
     step.__recorded = true;
     try { steps.push(step); } catch {}
+    if (stepsArchive && stepsArchive !== steps) {
+      try { stepsArchive.push(step); } catch {}
+    }
     try { ctx?.onStep?.(step); } catch {}
   };
   
@@ -190,7 +201,19 @@ export const turnLoop = async (
   for (let turn = currentTurn; turn < maxTurns; turn++) {
     console.log(`\n🔄 Turn ${turn + 1}/${maxTurns}`);
     let response;
-    const step = { turn, events: [], result: '🟡 In Progress', missionName };
+    const attempt = turnRetries + 1;
+    const step = {
+      turn,
+      retryAttempt: attempt,
+      retryLimit: retryLimitClamped, // number of retries allowed (excludes initial)
+      events: [],
+      result: '🟡 In Progress',
+      missionName,
+    };
+    if (attempt > 1) {
+      const retryNumber = attempt - 1;
+      step.events.push(`🔁 Re-attempt ${retryNumber}/${retryLimitClamped} for turn`);
+    }
 
     try {
       // Refresh token usage window (rolling 60 seconds)
@@ -211,7 +234,7 @@ export const turnLoop = async (
         step.events.push('❌ Tool call structure invalid and no placeholders inserted.');
         step.result = '❌ Failure';
         recordStep(step);
-        return steps;
+        return { success: false, steps: stepsArchive };
       }
 
       // Detect orphaned assistant tool calls with no matching tool responses
@@ -231,7 +254,7 @@ export const turnLoop = async (
         step.events.push('🛑 Detected assistant tool calls without matching tool responses');
         step.result = '❌ Failure';
         recordStep(step);
-        return steps;
+        return { success: false, steps: stepsArchive };
       }
 
       // Before calling the model, trim/sanitize the conversation context.
@@ -273,7 +296,7 @@ export const turnLoop = async (
           step.events.push('❌ Too many retries. Exiting.');
           step.result = '❌ Failure';
           recordStep(step);
-          return steps;
+          return { success: false, steps: stepsArchive };
         }
         retryCount += 1;
         turn -= 1;
@@ -283,7 +306,7 @@ export const turnLoop = async (
         step.events.push(`❌ Bad request: ${err.message}`);
         step.result = '❌ Failure';
         recordStep(step);
-        return steps;
+        return { success: false, steps: stepsArchive };
       } else {
         throw err;
       }
@@ -319,6 +342,7 @@ export const turnLoop = async (
     if (msg.tool_calls?.length) {
       console.log('Processing tool calls...');
       const toolResponses = [];
+      let hadToolIssues = false;
 
       for (const call of msg.tool_calls) {
         const fnName = call.function.name;
@@ -335,6 +359,7 @@ export const turnLoop = async (
         } catch (e) {
           errorMessage = `ERROR: ${e.message}`;
           result = errorMessage;
+          hadToolIssues = true;
         }
 
         // Capture and log any file upload/download events (for reports)
@@ -416,7 +441,21 @@ export const turnLoop = async (
 
       // Merge new assistant + tool responses back into conversation
       messages.push(msg, ...toolResponses);
-      step.result = '✅ Passed';
+      if (hadToolIssues && turnRetries < retryLimitClamped) {
+        step.result = '⏳ Retrying turn';
+        const retryNumber = attempt - 1;
+        step.events.push(`🔁 Re-attempt ${retryNumber}/${retryLimitClamped} after tool issues`);
+        recordStep(step);
+        turnRetries += 1;
+        const delay = Math.min(TURN_RETRY_BASE_DELAY_MS * 2 ** (turnRetries - 1), 2000);
+        await wait(delay);
+        turn -= 1; // re-use the same turn index
+        continue;
+      }
+
+      // reset retries after a clean turn or after exhausting retries
+      turnRetries = 0;
+      step.result = hadToolIssues ? '⚠️ Turn Issues' : '✅ Passed';
       recordStep(step);
       continue;
     }
@@ -429,7 +468,8 @@ export const turnLoop = async (
       step.events.push(finalResponse.finalMessage);
       step.result = finalResponse.success ? '✅ Mission Success' : '❌ Mission Failure';
       recordStep(step);
-      return { success: finalResponse.finalMessage, steps };
+      turnRetries = 0;
+      return { success: finalResponse.success, finalMessage: finalResponse.finalMessage, steps: stepsArchive };
     }
 
     // ─────────────────────────────────────────────
@@ -443,5 +483,8 @@ export const turnLoop = async (
     // This is a meaningful turn even without tool calls — record it.
     step.result = step.result || '🟡 In Progress';
     recordStep(step);
+    turnRetries = 0;
   }
+
+  return { success: false, steps: stepsArchive };
 };

package/package.json

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

package/runner/testronaut.js

@@ -25,7 +25,7 @@
 
 import { runAgent } from '../core/agent.js';
 import { redactPasswordInText } from '../core/redaction.js';
-import { loadConfig, enforceTurnBudget } from '../core/config.js';
+import { loadConfig, enforceTurnBudget, getRetryLimit } from '../core/config.js';
 
 /**
  * Run a mission flow.
@@ -38,9 +38,14 @@ export async function runMissions({ preMission, mission, postMission }, missionN
   const cfg = await loadConfig();
   const { effectiveMax, limits, notes } = enforceTurnBudget(cfg);
   const maxTurns = effectiveMax;
+  const retryInfo = getRetryLimit(cfg);
+  const retryLimit = retryInfo.value;
   if (notes.length) {
     console.warn(notes.join('\n'));
   }
+  if (retryInfo.clamped) {
+    console.warn(`⚠️ Retry limit clamped to ${retryLimit} (allowed range 1-10).`);
+  }
 
   // 2) Normalize submissions
   const normalizeToArray = (x) => (Array.isArray(x) ? x : x ? [x] : []);
@@ -123,7 +128,7 @@ export async function runMissions({ preMission, mission, postMission }, missionN
   );
 
   // 3) Execute
-  const success = await runAgent(goals, missionName, maxTurns);
+  const success = await runAgent(goals, missionName, maxTurns, retryLimit);
   if (!success) {
     console.log(`❌ Aborting after failed goal.`);
     return;

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

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import path from 'path';
+import fs from 'fs';
+
+// Import helper exports from cli.js
+import { __test__ } from '../../bin/cli.js';
+
+describe('cli helpers', () => {
+  it('guessMimeType returns expected types', () => {
+    const { guessMimeType } = __test__;
+    expect(guessMimeType('file.html')).toContain('text/html');
+    expect(guessMimeType('file.json')).toContain('application/json');
+    expect(guessMimeType('file.unknown')).toBe('application/octet-stream');
+  });
+
+  it('safeJoin prevents traversal', () => {
+    const { safeJoin } = __test__;
+    const root = '/tmp/root';
+    expect(safeJoin(root, '/sub/ok.txt')).toBe(path.resolve('/tmp/root/sub/ok.txt'));
+    expect(safeJoin(root, '/../etc/passwd')).toBeNull();
+  });
+
+  it('findLatestReportPair finds latest html/json', () => {
+    const { findLatestReportPair } = __test__;
+    const tmp = fs.mkdtempSync(path.join(process.cwd(), 'testronaut-report-'));
+    const r1 = path.join(tmp, 'run_100.html');
+    const r2 = path.join(tmp, 'run_200.html');
+    fs.writeFileSync(r1, 'a');
+    fs.writeFileSync(r2, 'b');
+    fs.writeFileSync(path.join(tmp, 'run_200.json'), '{}');
+
+    const latest = findLatestReportPair(tmp);
+    expect(latest?.htmlFile).toBe('run_200.html');
+    expect(latest?.jsonFile).toBe('run_200.json');
+  });
+});

package/tests/coreTests/config.test.js

@@ -8,6 +8,7 @@ import { readFile } from 'node:fs/promises';
 import {
   loadConfig,
   getMaxTurns,
+  getRetryLimit,
   resolveTurnLimits,
   enforceTurnBudget,
 } from '../../core/config.js';
@@ -64,6 +65,46 @@ describe('core/config', () => {
     });
   });
 
+  describe('getRetryLimit', () => {
+    const OLD_ENV = { ...process.env };
+    beforeEach(() => {
+      process.env = { ...OLD_ENV };
+      delete process.env.TESTRONAUT_RETRY_LIMIT;
+    });
+    afterEach(() => {
+      process.env = { ...OLD_ENV };
+    });
+
+    it('returns default when missing', () => {
+      const res = getRetryLimit({});
+      expect(res.value).toBe(2);
+      expect(res.source).toBe('default');
+      expect(res.clamped).toBe(false);
+    });
+
+    it('uses config value and clamps to range', () => {
+      expect(getRetryLimit({ retryLimit: 5 }).value).toBe(5);
+      const high = getRetryLimit({ retryLimit: 99 });
+      expect(high.value).toBe(10);
+      expect(high.clamped).toBe(true);
+      const low = getRetryLimit({ retryLimit: 0 });
+      expect(low.value).toBe(1);
+      expect(low.clamped).toBe(true);
+    });
+
+    it('prefers env over config and clamps', () => {
+      process.env.TESTRONAUT_RETRY_LIMIT = '8';
+      const res = getRetryLimit({ retryLimit: 3 });
+      expect(res.value).toBe(8);
+      expect(res.source).toBe('env');
+
+      process.env.TESTRONAUT_RETRY_LIMIT = '0';
+      const clampedLow = getRetryLimit({ retryLimit: 3 });
+      expect(clampedLow.value).toBe(1);
+      expect(clampedLow.clamped).toBe(true);
+    });
+  });
+
   describe('enforceTurnBudget (lenient)', () => {
     it('clamps > hardMaxTurns', () => {
       const cfg = { maxTurns: 1000 };

package/tests/coreTests/turnLoop.test.js

@@ -128,7 +128,7 @@ describe('turnLoop', () => {
     const messages = baseMessages();
     const result = await turnLoop(browser, messages, 1, 0, 0, {}, { steps: [], missionName: 'demo' });
 
-    expect(result).toBeTruthy();
+    expect(result.success).toBe(true);
     expect(result.steps?.length).toBe(1);
     const step = result.steps[0];
     expect(step.tokensUsed).toBe(42);
@@ -163,7 +163,7 @@ describe('turnLoop', () => {
     const messages = baseMessages();
     const res = await turnLoop(browser, messages, 2, 0, 0, {}, { steps: [], missionName: 'demo' });
 
-    expect(res).toBeTruthy();
+    expect(res.success).toBe(true);
     expect(res.steps.length).toBe(2);
 
     const step1 = res.steps[0];
@@ -174,4 +174,56 @@ describe('turnLoop', () => {
     const step2 = res.steps[1];
     expect(step2.result).toMatch(/Success/);
   });
+
+  it('retries a turn on tool error before marking issues', async () => {
+    // First turn: tool call → click_text will throw
+    shared.chatMock.mockResolvedValueOnce({
+      message: {
+        role: 'assistant',
+        content: '',
+        tool_calls: [
+          {
+            id: 'tool_retry',
+            type: 'function',
+            function: { name: 'click_text', arguments: JSON.stringify({ text: 'Hello' }) },
+          },
+        ],
+      },
+      usage: { total_tokens: 7 },
+    });
+    // Retry turn: same tool call, click_text succeeds
+    shared.chatMock.mockResolvedValueOnce({
+      message: {
+        role: 'assistant',
+        content: '',
+        tool_calls: [
+          {
+            id: 'tool_retry_2',
+            type: 'function',
+            function: { name: 'click_text', arguments: JSON.stringify({ text: 'Hello' }) },
+          },
+        ],
+      },
+      usage: { total_tokens: 6 },
+    });
+    // Final turn: mission completes
+    shared.chatMock.mockResolvedValueOnce({
+      message: { role: 'assistant', content: 'FINAL: done' },
+      usage: { total_tokens: 5 },
+    });
+
+    // click_text fails once, then succeeds
+    shared.chromeToolSpies.click_text
+      .mockImplementationOnce(async () => { throw new Error('no locator'); })
+      .mockImplementationOnce(async () => JSON.stringify({ ok: true, clicked: 'Hello' }));
+
+    const messages = baseMessages();
+    const res = await turnLoop(browser, messages, 3, 0, 0, {}, { steps: [], missionName: 'demo' });
+
+    expect(res.success).toBe(true);
+    expect(res.steps.length).toBe(3);
+    expect(res.steps[0].result).toBe('⏳ Retrying turn');
+    expect(res.steps[1].result).toBe('✅ Passed');
+    expect(res.steps[2].result).toMatch(/Success/);
+  });
 });

package/tests/runnerTests/testronaut.test.js

@@ -9,10 +9,11 @@ vi.mock('../../core/redaction.js', () => ({
 vi.mock('../../core/config.js', () => ({
   loadConfig: vi.fn(),
   enforceTurnBudget: vi.fn(),
+  getRetryLimit: vi.fn(),
 }));
 
 import { runAgent } from '../../core/agent.js';
-import { loadConfig, enforceTurnBudget } from '../../core/config.js';
+import { loadConfig, enforceTurnBudget, getRetryLimit } from '../../core/config.js';
 
 // Adjust the import path if your file lives elsewhere
 import { runMissions } from '../../runner/testronaut.js';
@@ -20,6 +21,8 @@ import { runMissions } from '../../runner/testronaut.js';
 describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    // Default retry limit unless overridden in a test
+    getRetryLimit.mockReturnValue({ value: 2, source: 'default', clamped: false });
   });
 
   it('passes effectiveMax to runAgent and logs any notes', async () => {
@@ -30,6 +33,7 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
       notes: ['⚠️ maxTurns (999) exceeds hardMaxTurns (200). Clamping to 200.'],
       strict: false,
     });
+    getRetryLimit.mockReturnValue({ value: 2, source: 'default', clamped: false });
 
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
     const log = vi.spyOn(console, 'log').mockImplementation(() => {});
@@ -46,7 +50,7 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
       expect.stringContaining('Clamping to 200')
     );
     expect(runAgent).toHaveBeenCalledWith(
-      expect.any(Array), 'Budgeted Run', 200
+      expect.any(Array), 'Budgeted Run', 200, 2
     );
 
     warn.mockRestore();
@@ -61,6 +65,7 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
       notes: [],
       strict: false,
     });
+    getRetryLimit.mockReturnValue({ value: 3, source: 'default', clamped: false });
 
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
     const log = vi.spyOn(console, 'log').mockImplementation(() => {});
@@ -72,7 +77,7 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
     await runMissions({ mission: 'No warnings' }, 'Clean');
 
     expect(warn).not.toHaveBeenCalled();
-    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'Clean', 20);
+    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'Clean', 20, 3);
 
     warn.mockRestore();
     log.mockRestore();
@@ -138,8 +143,8 @@ describe('cli/testronaut.runMissions (with enforceTurnBudget)', () => {
     // Mission name is the passed-in missionName for main
     expect(goals[1].submissionName).toMatch(/^My Mission/);
 
-    // Effective max turns passed through
-    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'My Mission', 15);
+    // Effective max turns and retry limit passed through
+    expect(runAgent).toHaveBeenCalledWith(expect.any(Array), 'My Mission', 15, 2);
 
     log.mockRestore();
   });

package/tests/toolsTests/generateHtmlReport.test.js

@@ -0,0 +1,90 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { generateHtmlReport } from '../../tools/generateHtmlReport.js';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'testronaut-report-'));
+});
+
+afterEach(() => {
+  try {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  } catch {}
+});
+
+describe('generateHtmlReport', () => {
+  it('writes an HTML report containing mission and retry metadata', () => {
+    const report = {
+      runId: 'run_test',
+      missions: [
+        {
+          missionName: 'Mission A',
+          submissionType: 'mission',
+          submissionName: 'Main',
+          status: 'passed',
+          steps: [
+            {
+              turn: 0,
+              retryAttempt: 2,
+              retryLimit: 5,
+              events: ['did something'],
+              result: '⚠️ Turn Issues',
+              summary: 'Do thing',
+              tokensUsed: 10,
+              totalTokensUsed: 20,
+            },
+          ],
+        },
+      ],
+    };
+
+    const outPath = path.join(tmpDir, 'report.html');
+    const written = generateHtmlReport(report, outPath);
+
+    expect(written).toBe(outPath);
+    expect(fs.existsSync(outPath)).toBe(true);
+    const html = fs.readFileSync(outPath, 'utf8');
+
+    expect(html).toContain('Testronaut Report');
+    expect(html).toContain('Mission A');
+    expect(html).toContain('Turn 1 (re-attempt 1/5)');
+    expect(html).toContain('⚠️ Turn Issues');
+  });
+
+  it('escapes unsafe text in output', () => {
+    const report = {
+      runId: 'run<&>',
+      missions: [
+        {
+          missionName: 'Mission <X>',
+          submissionType: 'mission',
+          submissionName: 'Main',
+          status: 'passed',
+          steps: [
+            {
+              turn: 0,
+              retryAttempt: 1,
+              events: ['<script>alert(1)</script>'],
+              result: '✅ Passed',
+              summary: '<b>bold</b>',
+            },
+          ],
+        },
+      ],
+    };
+
+    const outPath = path.join(tmpDir, 'safe.html');
+    generateHtmlReport(report, outPath);
+    const html = fs.readFileSync(outPath, 'utf8');
+
+    expect(html).toContain('run&lt;&amp;&gt;');
+    expect(html).toContain('Mission &lt;X&gt;');
+    expect(html).toContain('&lt;script&gt;alert(1)&lt;/script&gt;');
+    expect(html).toContain('&lt;b&gt;bold&lt;/b&gt;');
+  });
+});

package/tools/generateHtmlReport.js

@@ -1,7 +1,30 @@
-// generateHtmlReport.js
+/**
+ * generateHtmlReport.js
+ * ---------------------
+ * Purpose:
+ *   Render a Testronaut run summary into a single, self-contained HTML file.
+ *
+ * Responsibilities:
+ *   - Escape and format mission/step data into a readable report.
+ *   - Group submissions by mission and surface per-step metadata (tokens, retries).
+ *   - Write the HTML to disk at the provided output path (or a default location).
+ *
+ * Related tests:
+ *   tests/toolsTests/generateHtmlReport.test.js
+ *
+ * Used by:
+ *   - CLI report generation and upload flows.
+ */
 import fs from 'fs';
 import path from 'path';
 
+/**
+ * Render and write a Testronaut run report to disk.
+ *
+ * @param {object} report - normalized run JSON (runId, missions, summary, llm, etc.)
+ * @param {string} [outputPath] - optional absolute/relative path for the HTML file
+ * @returns {string} absolute path to the written HTML file
+ */
 export function generateHtmlReport(report, outputPath) {
   const { runId, startTime, endTime, missions = [], summary = {}, llm = {} } = report;
   const durationSec =
@@ -9,7 +32,7 @@ export function generateHtmlReport(report, outputPath) {
       ? ((new Date(endTime) - new Date(startTime)) / 1000).toFixed(2)
       : '—';
 
-  // helpers
+  // Escaping helpers for text and HTML attributes
   const esc = (s) => String(s ?? '')
     .replace(/&/g, '&amp;').replace(/</g, '&lt;')
     .replace(/>/g, '&gt;');
@@ -28,6 +51,17 @@ export function generateHtmlReport(report, outputPath) {
     const stepItems = steps.map((step, idx) => {
       const events = Array.isArray(step.events) ? step.events : [];
       const ok = /✅|Passed|Mission Success/i.test(step.result || '');
+      const resultRaw = step.result || '—';
+      const resultTooltip = resultRaw.includes('⚠️ Turn Issues')
+        ? 'Turn had tool/action issues (e.g., selector/timeouts). It may not indicate a product bug.'
+        : '';
+      const retryAttempt = step.retryAttempt || 1; // includes initial
+      const retryLimit = step.retryLimit; // number of retries allowed (excludes initial)
+      const retryNumber = retryAttempt - 1;
+      const retryTotal = Number.isFinite(retryLimit) ? retryLimit : Math.max(retryNumber, 0);
+      const attemptLabel = retryNumber > 0
+        ? ` (re-attempt ${retryNumber}/${retryTotal || retryNumber})`
+        : '';
       const imgTag = step.screenshotPath
         ? `<img src="${esc(step.screenshotPath)}" alt="screenshot turn ${esc(step.turn ?? idx)}">`
         : '';
@@ -42,9 +76,9 @@ export function generateHtmlReport(report, outputPath) {
       return `
         <details class="step" ${ok ? '' : 'open'}>
           <summary>
-            <span class="turn">Turn ${esc((step.turn ?? idx) + 1)}</span>
+            <span class="turn">Turn ${esc((step.turn ?? idx) + 1)}${esc(attemptLabel)}</span>
             ${planSpan}
-            <span class="step-result ${ok ? 'ok' : 'bad'}">${esc(step.result || '—')}</span>
+            <span class="step-result ${ok ? 'ok' : 'bad'}" ${resultTooltip ? `title="${escAttr(resultTooltip)}"` : ''}>${esc(resultRaw)}</span>
             <span class="tokens">tokens: ${esc(step.tokensUsed ?? '—')} / total: ${esc(step.totalTokensUsed ?? '—')}</span>
           </summary>
           <pre class="events">${esc(events.join('\n')) || '(no events)'}</pre>