testronaut 1.6.0 → 1.6.2

package/README.md

@@ -58,12 +58,18 @@ testronaut --init
 Run the sample mission:
 ```bash
 testronaut welcome.mission.js
+
+# Paths work too, which enables shell tab completion
+testronaut missions/welcome.mission.js
 ```
 
 **One-off / no install** (use `npx` to run without installing):
 ```bash
 npx testronaut --init
 npx testronaut welcome.mission.js
+
+# Paths work too, which enables shell tab completion
+npx testronaut missions/welcome.mission.js
 ```
 
 ---
@@ -74,9 +80,13 @@ npx testronaut welcome.mission.js
 missions/
 ├── login.mission.js
 ├── logout.mission.js
-└── dashboard.mission.js
+└── dashboard.mission.ts
 ```
 
+Mission files can use standard `import`/`export` syntax in `.js` or `.ts` files.
+Testronaut loads them independently of your project's module format, so your
+`package.json` does not need `"type": "module"`.
+
 Each mission exports a string or function and calls `runMissions`.
 
 ---
@@ -153,6 +163,20 @@ Run a specific mission:
 testronaut login.mission.js
 ```
 
+Preview or inspect without launching a browser:
+```bash
+testronaut list
+testronaut --dry-run
+testronaut config
+```
+
+Upload the latest or a selected report:
+```bash
+testronaut upload
+testronaut upload run_1788745106444
+testronaut upload run_1788745106444.json --no-upload-screenshots
+```
+
 Chain missions together:
 ```js
 await runMissions({
@@ -243,7 +267,7 @@ Notes:
 
 ## 📋 Reports
 
-Testronaut generates both JSON and HTML reports automatically under:
+Testronaut generates JSON, HTML, and run-specific screenshots under the configured `outputDir` (default):
 
 ```
 missions/mission_reports/

package/TODO.md

@@ -1,5 +1,14 @@
 # TODO
 
+## Quality-of-Life Follow-Ups
+
+- [ ] Add a versioned report schema shared with Mission Control so future report changes can be validated and migrated explicitly.
+- [ ] Add resumable, retryable, and idempotent report uploads so interrupted screenshot transfers do not require starting over or create duplicate reports.
+- [ ] Add `testronaut doctor` to check Node.js, browser installation, configuration, authentication, output-directory access, and API connectivity without running a mission.
+- [ ] Add optional shell completion for commands, flags, mission files, tags, and local report IDs.
+- [ ] Treat `--json` output as a stable automation contract with documented schemas and tests for every supported command.
+- [ ] If authentication ever moves outside project config, continue reading existing `sessionToken` values and provide an opt-in migration path before deprecating legacy storage.
+
 ## Automated MFA Follow-Ups
 
 - [ ] Add an integration smoke test against a local or staging API fixture for `get_mfa_code`.

package/bin/cli.js

@@ -34,6 +34,9 @@
  *   See tests in tests/toolsTests/cli.helpers.test.js
  */
 
+// Missions often interpolate project .env values while their modules load.
+// Load those values before discovery imports any user-authored mission code.
+import 'dotenv/config';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -51,6 +54,7 @@ const exec = promisify(execCmd);
 import url from 'url';
 import { ensureBrowsers } from '../tools/playwrightSetup.js';
 import { discoverMissionFiles } from '../core/missionDiscovery.js';
+import { loadMissionModule } from '../core/missionLoader.js';
 import { loadConfig } from '../core/config.js';
 import { matchesTagFilter, normalizeTagMatch, normalizeTags } from '../core/tags.js';
 
@@ -59,12 +63,32 @@ process.env.PLAYWRIGHT_BROWSERS_PATH = process.env.PLAYWRIGHT_BROWSERS_PATH || '
 
 const TMP_DIR = path.resolve('./missions/tmp');
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_VERSION = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, '../package.json'), 'utf8')
+).version;
 
 const DEFAULT_API_BASE = 'http://api.testronaut.app';
 const DEV_API_BASE = 'https://staging.api.testronaut.app';
 
 let args = process.argv.slice(2);
 
+const jsonOutput = args.includes('--json');
+const quietOutput = args.includes('--quiet') || jsonOutput;
+args = args.filter(arg => arg !== '--json' && arg !== '--quiet');
+const writeOutput = value => process.stdout.write(`${typeof value === 'string' ? value : JSON.stringify(value, null, 2)}\n`);
+if (quietOutput) {
+  console.log = () => {};
+  console.warn = () => {};
+}
+
+const dryRun = args.includes('--dry-run');
+args = args.filter(arg => arg !== '--dry-run');
+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');
+process.env.TESTRONAUT_SCREENSHOTS = screenshotsEnabled ? '1' : '0';
+
 // Detect how the CLI was invoked so help text matches the actual command
 function detectCliName(npmCommand = process.env.npm_command, argv1 = process.argv[1]) {
   // npx sets npm_command to 'exec'
@@ -311,8 +335,97 @@ export const __test__ = {
   parseRunOptionsArgs,
   detectCliName,
   isDirectInvocation,
+  resolveMissionPath,
+  collectReportScreenshotNames,
+  collectReportScreenshotPaths,
+  resolveReportDir,
+  closestMissionMatch,
+  resolveReportFile,
+  buildEffectiveConfig,
 };
 
+function resolveReportDir(config = {}, cwd = process.cwd()) {
+  return path.resolve(cwd, config.outputDir || 'missions/mission_reports');
+}
+
+function resolveReportFile(requested, reportDir, cwd = process.cwd()) {
+  if (!requested) return null;
+  const names = path.extname(requested) ? [requested] : [requested, `${requested}.json`];
+  for (const name of names) {
+    const direct = path.resolve(cwd, name);
+    if (fs.existsSync(direct)) return direct;
+    const inReportDir = path.resolve(reportDir, name);
+    if (fs.existsSync(inReportDir)) return inReportDir;
+  }
+  return path.resolve(reportDir, names.at(-1));
+}
+
+function buildEffectiveConfig(config = {}, cwd = process.cwd()) {
+  const resolved = resolveProviderModel({ cwd });
+  const source = key => process.env[key] ? 'environment' : undefined;
+  return {
+    configFile: path.resolve(cwd, 'testronaut-config.json'),
+    provider: { value: resolved.provider, source: source('TESTRONAUT_PROVIDER') || (config.provider ? 'config' : 'default') },
+    model: { value: resolved.model, source: source('TESTRONAUT_MODEL') || (config.model ? 'config' : 'default') },
+    outputDir: { value: resolveReportDir(config, cwd), source: config.outputDir ? 'config' : 'default' },
+    maxTurns: { value: Number(process.env.TESTRONAUT_TURNS || config.maxTurns || 20), source: source('TESTRONAUT_TURNS') || (config.maxTurns != null ? 'config' : 'default') },
+    tags: config.tags || [],
+    tagMatch: config.tagMatch || 'any',
+    addTags: normalizeTags([...(config.addTags || []), ...cliAddTags]),
+    screenshots: screenshotsEnabled,
+    authenticated: Boolean(config.sessionToken),
+  };
+}
+
+function closestMissionMatch(requested, candidates = []) {
+  const target = path.basename(requested).toLowerCase();
+  const distance = (a, b) => {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+      let previous = row[0];
+      row[0] = i;
+      for (let j = 1; j <= b.length; j++) {
+        const saved = row[j];
+        row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+        previous = saved;
+      }
+    }
+    return row[b.length];
+  };
+  return candidates
+    .map(file => ({ file, distance: distance(target, path.basename(file).toLowerCase()) }))
+    .sort((a, b) => a.distance - b.distance || a.file.localeCompare(b.file))[0]?.file || null;
+}
+
+function resolveMissionPath(filePath, { cwd = process.cwd(), missionsRoot } = {}) {
+  if (path.isAbsolute(filePath)) return path.normalize(filePath);
+
+  const directPath = path.resolve(cwd, filePath);
+  const hasPathSegments = path.dirname(filePath) !== '.';
+  if (hasPathSegments || fs.existsSync(directPath)) return directPath;
+
+  return path.resolve(missionsRoot || path.join(cwd, 'missions'), filePath);
+}
+
+function collectReportScreenshotNames(report) {
+  return collectReportScreenshotPaths(report).map(file => path.basename(file));
+}
+
+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('\\', '/');
+      if (!name || seen.has(name)) continue;
+      seen.add(name);
+      names.push(name);
+    }
+  }
+  return names;
+}
+
 function parseTagArgs(argsList) {
   const nextArgs = [];
   const tagValues = [];
@@ -603,9 +716,11 @@ const HELP_TEXT = `
 
 Usage:
   ${cliName}                 Run all missions in the ./missions directory
-  ${cliName} <file>         Run a specific mission file (e.g., login.mission.js)
+  ${cliName} <file>         Run a .mission.js or .mission.ts file by name or path
   ${cliName} login          Log in and store session token
-  ${cliName} upload         Upload the most recent report JSON
+  ${cliName} list           List discovered missions and tags without running them
+  ${cliName} config         Show effective configuration and value sources
+  ${cliName} upload [file]  Upload the latest report or a selected report file/run ID
   ${cliName} serve        Serve & open the most recent HTML report (read-only)
   ${cliName} view         Alias of 'serve'
 
@@ -621,6 +736,11 @@ Options:
   --no-human-input          Disable human-in-the-loop verification prompts for automated runs
   --human-input-timeout=<s> Override human input wait timeout in seconds (default: 60)
   --help                    Show this help message
+  --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
+  --json                    Emit machine-readable command/run output
+  --quiet                   Suppress informational logs
   --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)
@@ -631,6 +751,7 @@ Options:
 Examples:
   ${cliName}
   ${cliName} login
+  ${cliName} list
   ${cliName} upload
   ${cliName} serve
   ${cliName} --init
@@ -689,8 +810,8 @@ if (args.includes('login')) {
 }
 
 // Handle the upload command
-if (args.includes('upload')) {
-  await uploadReport();
+if (args[0] === 'upload') {
+  await uploadReport(args[1], { uploadScreenshots });
   process.exit(0);
 }
 
@@ -704,6 +825,37 @@ if (args.includes('serve') || args.includes('view')) {
 
 const { root: missionsRoot, files: discoveredMissions } = await discoverMissionFiles({ cwd: process.cwd() });
 const tagConfig = await loadConfig(process.cwd());
+const outputDir = resolveReportDir(tagConfig);
+process.env.TESTRONAUT_OUTPUT_DIR = outputDir;
+process.env.TESTRONAUT_RUN_ID = runId;
+
+if (args.length === 1 && args[0] === 'config') {
+  writeOutput(buildEffectiveConfig(tagConfig));
+  return;
+}
+
+if (args.length === 1 && args[0] === 'list') {
+  if (!discoveredMissions.length) {
+    writeOutput(jsonOutput ? { missions: [], root: missionsRoot } : `No missions found in ${path.relative(process.cwd(), missionsRoot) || '.'}.`);
+    return;
+  }
+  const listedMissions = [];
+  if (!jsonOutput) console.log(`Missions in ${path.relative(process.cwd(), missionsRoot) || '.'}:`);
+  for (const file of discoveredMissions) {
+    try {
+      const mission = await loadMissionModule(path.resolve(missionsRoot, file));
+      const tags = normalizeTags(mission.tags);
+      listedMissions.push({ file, tags });
+      if (!jsonOutput) console.log(`  ${file}${tags.length ? `  [${tags.join(', ')}]` : ''}`);
+    } catch (error) {
+      console.log(`  ${file}  [could not load: ${error.message}]`);
+      process.exitCode = 1;
+    }
+  }
+  if (jsonOutput) writeOutput({ root: missionsRoot, missions: listedMissions });
+  return;
+}
+
 const explicitFiles = args.length > 0;
 let requestedTags = [];
 let tagMatch = 'any';
@@ -719,32 +871,71 @@ try {
   process.exit(1);
 }
 
-if (!fs.existsSync(missionsRoot)) {
+if (!explicitFiles && !fs.existsSync(missionsRoot)) {
   console.error(`❌ Missions directory not found: ${path.relative(process.cwd(), missionsRoot)}`);
   process.exit(1);
 }
 
+if (dryRun) {
+  const candidates = explicitFiles ? args : discoveredMissions;
+  const missions = [];
+  let invalid = false;
+  for (const file of candidates) {
+    const modulePath = resolveMissionPath(file, { cwd: process.cwd(), missionsRoot });
+    if (!fs.existsSync(modulePath)) {
+      missions.push({ file, status: 'missing', suggestion: closestMissionMatch(file, discoveredMissions) });
+      invalid = true;
+      continue;
+    }
+    try {
+      const mission = await loadMissionModule(modulePath);
+      const tags = normalizeTags(mission.tags);
+      const selected = explicitFiles || matchesTagFilter(tags, requestedTags, tagMatch);
+      missions.push({ file: path.relative(process.cwd(), modulePath), tags, selected, valid: typeof mission.executeMission === 'function' });
+      if (typeof mission.executeMission !== 'function') invalid = true;
+    } catch (error) {
+      missions.push({ file, status: 'load-error', error: error.message });
+      invalid = true;
+    }
+  }
+  writeOutput({ dryRun: true, outputDir, provider: resolveProviderModel({ cwd: process.cwd() }), screenshots: screenshotsEnabled, missions });
+  if (invalid) process.exitCode = 1;
+  return;
+}
+
 const runFile = async (filePath) => {
+  const modulePath = resolveMissionPath(filePath, { cwd: process.cwd(), missionsRoot });
   try {
-    const modulePath = path.resolve(missionsRoot, filePath);
-    const missionsModule = await import(`file://${modulePath}`);
+    if (!fs.existsSync(modulePath)) {
+      const suggestion = closestMissionMatch(filePath, discoveredMissions);
+      console.error(`❌ Mission file not found: ${filePath}`);
+      if (suggestion) console.error(`   Did you mean "${suggestion}"?`);
+      return false;
+    }
+    const missionsModule = await loadMissionModule(modulePath);
 
     if (!explicitFiles) {
       const moduleTags = normalizeTags(missionsModule.tags);
-      if (!matchesTagFilter(moduleTags, requestedTags, tagMatch)) return false;
+      if (!matchesTagFilter(moduleTags, requestedTags, tagMatch)) return null;
     }
 
     if (typeof missionsModule.executeMission === 'function') {
       const result = await missionsModule.executeMission();
+      if (result == null) {
+        console.error(`❌ Mission did not return a result: ${filePath}`);
+        return false;
+      }
       allResults.push({
-        file: filePath,
+        file: path.relative(process.cwd(), modulePath) || path.basename(modulePath),
         result
       });
-      return true;
+      const missionResults = Array.isArray(result) ? result : [result];
+      return !missionResults.some(item => item?.status === 'failed');
     }
+    console.error(`❌ Mission does not export executeMission(): ${filePath}`);
   } catch (err) {
     console.error(`❌ Error running mission: ${filePath}`);
-    console.error(err);
+    console.error(`   ${err?.message || err}`);
   }
   return false;
 };
@@ -752,20 +943,27 @@ const runFile = async (filePath) => {
 if (args.length > 0) {
   // Run specific file(s)
   for (const file of args) {
-    await runFile(file);
+    if (!await runFile(file)) process.exitCode = 1;
   }
 } else {
   // Run missions discovered from config (or default behavior)
   for (const file of discoveredMissions) {
-    await runFile(file);
+    if (await runFile(file) === false) process.exitCode = 1;
   }
 }
 
+if (!explicitFiles && discoveredMissions.length === 0) {
+  console.error(`❌ No mission files found in ${path.relative(process.cwd(), missionsRoot) || '.'}.`);
+  process.exit(1);
+}
+
 if (!explicitFiles && requestedTags.length && allResults.length === 0) {
   console.error(`❌ No missions matched ${tagMatch === 'all' ? 'all' : 'any'} of: ${requestedTags.join(', ')}`);
   process.exit(1);
 }
 
+if (allResults.length === 0) return;
+
 const endTime = new Date();
 
 const flatMissions = allResults.flatMap(entry => {
@@ -794,6 +992,7 @@ const { provider: llmProvider, model: llmModel } = resolveProviderModel({ cwd: p
 
 const report = {
   runId,
+  cli: { version: CLI_VERSION },
   startTime: startTime.toISOString(),
   endTime: endTime.toISOString(),
   llm: {
@@ -811,10 +1010,10 @@ report.tags = normalizeTags(flatMissions.flatMap(m =>
   m.submissionType === 'mission' ? (m.tags ?? []) : []
 ));
 
-const outputDir = './missions/mission_reports';
 fs.mkdirSync(outputDir, { recursive: true });
-fs.writeFileSync(`${outputDir}/${runId}.json`, JSON.stringify(report, null, 2));
-generateHtmlReport(report, `${outputDir}/${runId}.html`);
+fs.writeFileSync(path.join(outputDir, `${runId}.json`), JSON.stringify(report, null, 2));
+generateHtmlReport(report, path.join(outputDir, `${runId}.html`));
+if (jsonOutput) writeOutput(report);
 
   try {
     if (!process.env.TN_KEEP_TMP && fs.existsSync(TMP_DIR)) {
@@ -1010,7 +1209,7 @@ async function handleLogin() {
 }
 
 // Upload the most recent report
-async function uploadReport() {
+async function uploadReport(requestedReport, { uploadScreenshots: shouldUploadScreenshots = true } = {}) {
   const configPath = path.resolve(process.cwd(), 'testronaut-config.json');
   if (!fs.existsSync(configPath)) {
     console.error('❌ Configuration file not found.');
@@ -1025,16 +1224,29 @@ async function uploadReport() {
 
 
   // 1) Find latest report JSON
-  const reportDir = path.resolve(process.cwd(), 'missions/mission_reports');
-  const files = fs.readdirSync(reportDir).filter(f => f.endsWith('.json'));
-  if (files.length === 0) {
+  const reportDir = resolveReportDir(config);
+  if (!requestedReport && !fs.existsSync(reportDir)) {
+    console.error(`❌ Report directory not found: ${path.relative(process.cwd(), reportDir) || reportDir}`);
+    process.exit(1);
+  }
+  const files = fs.existsSync(reportDir) ? fs.readdirSync(reportDir).filter(f => f.endsWith('.json')) : [];
+  if (!requestedReport && files.length === 0) {
     console.error('❌ No report files found.');
     process.exit(1);
   }
   files.sort((a, b) => parseInt(b.split('_')[1]) - parseInt(a.split('_')[1]));
-  const latestReportFile = files[0];
-  const latestReportPath = path.join(reportDir, latestReportFile);
+  const selectedReportPath = requestedReport
+    ? resolveReportFile(requestedReport, reportDir)
+    : path.join(reportDir, files[0]);
+  if (!fs.existsSync(selectedReportPath)) {
+    console.error(`❌ Report file not found: ${requestedReport}`);
+    process.exit(1);
+  }
+  const latestReportPath = selectedReportPath;
+  const latestReportFile = path.basename(selectedReportPath);
   const reportJson = fs.readFileSync(latestReportPath, 'utf8');
+  const report = JSON.parse(reportJson);
+  const selectedReportDir = path.dirname(selectedReportPath);
 
   // 2) Upload report FIRST and capture its ID
   console.log(`🛰️  Uploading report: ${latestReportFile}`);
@@ -1061,10 +1273,17 @@ async function uploadReport() {
     process.exit(1);
   }
 
+  if (!shouldUploadScreenshots) {
+    console.log('ℹ️  Screenshot upload disabled. Report JSON upload complete.');
+    if (jsonOutput) writeOutput({ ok: true, reportId: savedReportId, report: latestReportFile, screenshotsUploaded: 0 });
+    return;
+  }
+
   // 3) Now find the fixed 'screenshots' folder next to JSON
-  const screenshotsDir = path.join(reportDir, 'screenshots');
+  const screenshotsDir = path.join(selectedReportDir, 'screenshots');
   if (!fs.existsSync(screenshotsDir) || !fs.statSync(screenshotsDir).isDirectory()) {
     console.log('ℹ️  No screenshots directory found. Done.');
+    if (jsonOutput) writeOutput({ ok: true, reportId: savedReportId, report: latestReportFile, screenshotsUploaded: 0 });
     return;
   }
 
@@ -1076,13 +1295,22 @@ async function uploadReport() {
     return Date.UTC(+Y, +M - 1, +D, +h, +mnt, +s, +ms);
   };
 
-  let imageFiles = fs
-    .readdirSync(screenshotsDir)
-    .filter(f => /\.(png|jpg|jpeg|webp|gif)$/i.test(f))
-    .sort((a, b) => parseScreenshotTimestamp(a) - parseScreenshotTimestamp(b));
+  const imageFiles = collectReportScreenshotPaths(report)
+    .map(relativePath => ({
+      relativePath,
+      filePath: path.resolve(selectedReportDir, relativePath),
+    }))
+    .filter(({ filePath }) =>
+      filePath.startsWith(`${path.resolve(screenshotsDir)}${path.sep}`) &&
+      fs.existsSync(filePath) &&
+      fs.statSync(filePath).isFile() &&
+      /\.(png|jpg|jpeg|webp|gif)$/i.test(filePath)
+    )
+    .sort((a, b) => parseScreenshotTimestamp(path.basename(a.filePath)) - parseScreenshotTimestamp(path.basename(b.filePath)));
 
   if (!imageFiles.length) {
-    console.log('ℹ️  Screenshots directory is empty. Done.');
+    console.log('ℹ️  This report does not reference any available screenshots. Done.');
+    if (jsonOutput) writeOutput({ ok: true, reportId: savedReportId, report: latestReportFile, screenshotsUploaded: 0 });
     return;
   }
 
@@ -1101,11 +1329,10 @@ async function uploadReport() {
 
   const failures = [];
   for (let i = 0; i < imageFiles.length; i++) {
-    const f = imageFiles[i];
-    const filePath = path.join(screenshotsDir, f);
+    const { filePath, relativePath: f } = imageFiles[i];
     const stepIndex = i;
 
-    process.stdout.write(`   ➜ ${f} (step ${stepIndex}) … `);
+    if (!quietOutput) process.stdout.write(`   ➜ ${f} (step ${stepIndex}) … `);
     try {
       const buf = fs.readFileSync(filePath);
       const stat = fs.statSync(filePath);
@@ -1154,9 +1381,9 @@ async function uploadReport() {
       const finish = await parseJsonSafe(finishRes, 'uploads/finish');
       if (!finish.ok) throw new Error(`uploads/finish responded ok=false`);
 
-      process.stdout.write('ok\n');
+      if (!quietOutput) process.stdout.write('ok\n');
     } catch (err) {
-      process.stdout.write('FAIL\n');
+      if (!quietOutput) process.stdout.write('FAIL\n');
       failures.push({ file: f, error: err.message || String(err) });
     }
   }
@@ -1165,8 +1392,10 @@ async function uploadReport() {
     console.log('\n⚠️  Some screenshots failed to upload:');
     for (const f of failures) console.log(`   - ${f.file}: ${f.error}`);
     process.exitCode = 1;
+    if (jsonOutput) writeOutput({ ok: false, reportId: savedReportId, report: latestReportFile, screenshotsUploaded: imageFiles.length - failures.length, failures });
   } else {
     console.log('✅ All screenshots uploaded.');
+    if (jsonOutput) writeOutput({ ok: true, reportId: savedReportId, report: latestReportFile, screenshotsUploaded: imageFiles.length });
   }
 }
 
@@ -1248,11 +1477,12 @@ function findLatestReportPair(reportDir) {
 }
 
 async function serveLatestReport() {
-  const reportDir = path.resolve(process.cwd(), 'missions/mission_reports');
+  const config = await loadConfig(process.cwd());
+  const reportDir = resolveReportDir(config);
 
   const latest = findLatestReportPair(reportDir);
   if (!latest) {
-    console.error('❌ No HTML reports found in missions/mission_reports.');
+    console.error(`❌ No HTML reports found in ${path.relative(process.cwd(), reportDir) || reportDir}.`);
     process.exit(1);
   }
 

package/bin/init.js

@@ -43,7 +43,6 @@ export async function initializeTestronautProject() {
   // ─────────────────────────────────────────────
   const root = process.cwd();
   const missionsDir = path.join(root, 'missions');
-  const reportsDir = path.join(missionsDir, 'mission_reports');
   const configPath = path.join(root, 'testronaut-config.json');
   const envPath = path.join(root, '.env');
 
@@ -139,6 +138,9 @@ export async function initializeTestronautProject() {
     config.outputDir = config.outputDir || defaults.outputDir;
     config.projectName = config.projectName || defaults.projectName;
     config.maxTurns = config.maxTurns ?? defaults.maxTurns;
+    config.tags = config.tags ?? defaults.tags;
+    config.tagMatch = config.tagMatch ?? defaults.tagMatch;
+    config.addTags = config.addTags ?? defaults.addTags;
     config.dom = { ...defaults.dom, ...(config.dom || {}) };
     config.resourceGuard = { ...defaults.resourceGuard, ...(config.resourceGuard || {}) };
     config.humanInput = { ...defaults.humanInput, ...(config.humanInput || {}) };
@@ -197,12 +199,13 @@ export async function initializeTestronautProject() {
   // ─────────────────────────────────────────────
   // STEP 5: Ensure folder structure exists (safe to call every run)
   // ─────────────────────────────────────────────
+  const reportsDir = path.resolve(root, config.outputDir || 'missions/mission_reports');
   if (!fs.existsSync(missionsDir)) {
     fs.mkdirSync(missionsDir);
     console.log('📁 Created missions/');
   }
   if (!fs.existsSync(reportsDir)) {
     fs.mkdirSync(reportsDir);
-    console.log('📁 Created missions/mission_reports/');
+    console.log(`📁 Created ${path.relative(root, reportsDir) || reportsDir}/`);
   }
 }

package/core/missionDiscovery.js

@@ -9,7 +9,7 @@ const DEFAULT_INCLUDE = ['**/*.mission.js', '**/*.mission.ts'];
 /**
  * Discover mission files based on testronaut-config.json.
  * - When no missions block exists, preserve legacy behavior:
- *   read the ./missions folder (non-recursive) for *.mission.js files.
+ *   read the ./missions folder (non-recursive) for JavaScript/TypeScript missions.
  * - When missions is defined, apply root/include/exclude globs relative to root.
  *
  * @param {object} opts
@@ -21,13 +21,13 @@ export async function discoverMissionFiles({ cwd = process.cwd() } = {}) {
   const cfg = await loadConfig(cwd);
   const missionsCfg = cfg?.missions;
 
-  // Legacy behavior: no missions block → non-recursive *.mission.js in ./missions
+  // Legacy behavior remains non-recursive, now with first-class TypeScript support.
   if (!missionsCfg) {
     if (!fs.existsSync(defaultRoot)) {
       return { root: defaultRoot, files: [] };
     }
     const files = fs.readdirSync(defaultRoot)
-      .filter(f => f.endsWith('.mission.js'))
+      .filter(f => f.endsWith('.mission.js') || f.endsWith('.mission.ts'))
       .sort();
     return { root: defaultRoot, files };
   }

package/core/missionLoader.js

@@ -0,0 +1,16 @@
+import { createJiti } from 'jiti';
+
+// Mission files are user-authored configuration/code, so Testronaut owns their
+// module loading semantics instead of inheriting the host project's package type.
+const jiti = createJiti(import.meta.url, {
+  interopDefault: true,
+  sourceMaps: true,
+});
+
+/**
+ * Load an ESM-style JavaScript or TypeScript mission regardless of whether the
+ * consuming project is ESM, CommonJS, or has no package.json `type` field.
+ */
+export async function loadMissionModule(modulePath) {
+  return jiti.import(modulePath);
+}

package/core/turnLoop.js

@@ -156,6 +156,8 @@ const FIRE_AND_FORGET_TOOLS = new Set([
   'switch_to_page',
   'close_current_page',
   'request_human_input',
+  'set_ground_control_state',
+  'record_mission_telemetry',
 ]);
 
 /**
@@ -252,9 +254,10 @@ export const turnLoop = async (
   const maxAttempts = retryLimitClamped + 1; // includes initial attempt
   ctx.groundControl = groundControl;
   const humanInput = ctx.humanInput || { enabled: true, timeoutSeconds: 60 };
-  const activeToolsSchema = humanInput.enabled === false
-    ? toolsSchema.filter(t => t?.function?.name !== 'request_human_input')
-    : toolsSchema;
+  const disabledTools = new Set();
+  if (humanInput.enabled === false) disabledTools.add('request_human_input');
+  if (process.env.TESTRONAUT_SCREENSHOTS === '0') disabledTools.add('screenshot');
+  const activeToolsSchema = toolsSchema.filter(t => !disabledTools.has(t?.function?.name));
   let agentMemory = { lastMenuExpanded: false, humanInput };
   ensureDocProgress(agentMemory, resourceGuardCfg);
   let turnRetries = 0;
@@ -433,7 +436,17 @@ export const turnLoop = async (
         let result;
         let errorMessage = null;
         try {
-          result = await CHROME_TOOL_MAP[fnName](browser, args, agentMemory);
+          if (fnName === 'set_ground_control_state') {
+            applyGroundControlUpdate(groundControl, args);
+            result = { ok: true, groundControl };
+          } else if (fnName === 'record_mission_telemetry') {
+            const recorded = recordGroundTelemetry(groundControl, args, { turn });
+            result = { ok: true, recorded };
+          } else {
+            const toolHandler = CHROME_TOOL_MAP[fnName];
+            if (typeof toolHandler !== 'function') throw new Error(`Unknown tool: ${fnName}`);
+            result = await toolHandler(browser, args, agentMemory);
+          }
           if (typeof result !== 'string') result = JSON.stringify(result ?? '');
         } catch (e) {
           errorMessage = `ERROR: ${e.message}`;
@@ -649,16 +662,6 @@ export const turnLoop = async (
           }
         }
 
-        if (fnName === 'set_ground_control_state') {
-          applyGroundControlUpdate(groundControl, args);
-          result = JSON.stringify({ ok: true, groundControl });
-        }
-
-        if (fnName === 'record_mission_telemetry') {
-          const recorded = recordGroundTelemetry(groundControl, args, { turn });
-          result = JSON.stringify({ ok: true, recorded });
-        }
-
         // Decide what to send back to the LLM for this tool.
         // - For "fire-and-forget" tools, send a tiny stub (OK/error) to avoid
         //   bloating context with large payloads (file JSON, etc.).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testronaut",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "main": "./runner/testronaut.js",
   "bin": {
     "testronaut": "bin/cli.js"
@@ -30,6 +30,7 @@
     "dotenv": "^17.2.0",
     "fast-glob": "^3.3.3",
     "inquirer": "^12.9.1",
+    "jiti": "^2.7.0",
     "node-fetch": "^3.3.2",
     "openai": "^6.39.0",
     "playwright": "^1.54.1",

package/runner/testronaut.js

@@ -23,9 +23,11 @@
  */
 
 
+// Mission modules commonly interpolate project .env values at module load time.
+// Keep env loading eager even though the browser/agent import below is lazy.
+import 'dotenv/config';
 import fs from 'fs';
 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';
@@ -202,6 +204,7 @@ export async function runMissions({ preMission, mission, postMission, tags = []
   );
 
   // 3) Execute
+  const { runAgent } = await import('../core/agent.js');
   const success = await runAgent(
     goals,
     missionName,

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

@@ -1,10 +1,22 @@
-import { describe, it, expect } from 'vitest';
+import { afterEach, describe, it, expect } from 'vitest';
 import path from 'path';
 import fs from 'fs';
+import os from 'os';
 
 // Import helper exports from cli.js
 import { __test__ } from '../../bin/cli.js';
 
+const tempDirs = [];
+const makeTempDir = (prefix) => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+};
+
+afterEach(() => {
+  while (tempDirs.length) fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+});
+
 describe('cli helpers', () => {
   it('guessMimeType returns expected types', () => {
     const { guessMimeType } = __test__;
@@ -22,7 +34,7 @@ describe('cli helpers', () => {
 
   it('findLatestReportPair finds latest html/json', () => {
     const { findLatestReportPair } = __test__;
-    const tmp = fs.mkdtempSync(path.join(process.cwd(), 'testronaut-report-'));
+    const tmp = makeTempDir('testronaut-report-');
     const r1 = path.join(tmp, 'run_100.html');
     const r2 = path.join(tmp, 'run_200.html');
     fs.writeFileSync(r1, 'a');
@@ -34,6 +46,67 @@ describe('cli helpers', () => {
     expect(latest?.jsonFile).toBe('run_200.json');
   });
 
+  it('resolves bare mission names from the missions root and direct paths from cwd', () => {
+    const { resolveMissionPath } = __test__;
+    const cwd = '/tmp/project';
+    const missionsRoot = '/tmp/project/missions';
+    expect(resolveMissionPath('login.mission.js', { cwd, missionsRoot }))
+      .toBe('/tmp/project/missions/login.mission.js');
+    expect(resolveMissionPath('missions/login.mission.js', { cwd, missionsRoot }))
+      .toBe('/tmp/project/missions/login.mission.js');
+    expect(resolveMissionPath('../shared/login.mission.js', { cwd, missionsRoot }))
+      .toBe('/tmp/shared/login.mission.js');
+  });
+
+  it('collects only unique screenshots referenced by a report', () => {
+    const { collectReportScreenshotNames, collectReportScreenshotPaths } = __test__;
+    const report = { missions: [
+      { steps: [{ screenshotPath: './screenshots/one.png' }, { screenshotPath: './screenshots/two.jpg' }] },
+      { steps: [{ screenshotPath: './screenshots/one.png' }, { events: [] }] },
+    ] };
+    expect(collectReportScreenshotNames(report)).toEqual(['one.png', 'two.jpg']);
+    expect(collectReportScreenshotPaths(report)).toEqual(['screenshots/one.png', 'screenshots/two.jpg']);
+  });
+
+  it('preserves run-specific screenshot paths', () => {
+    const { collectReportScreenshotPaths } = __test__;
+    const report = { missions: [{ steps: [
+      { screenshotPath: './screenshots/run_123/one.png' },
+    ] }] };
+    expect(collectReportScreenshotPaths(report)).toEqual(['screenshots/run_123/one.png']);
+  });
+
+  it('resolves configured report directories and suggests close mission names', () => {
+    const { resolveReportDir, closestMissionMatch } = __test__;
+    expect(resolveReportDir({ outputDir: 'artifacts/reports' }, '/tmp/project'))
+      .toBe('/tmp/project/artifacts/reports');
+    expect(closestMissionMatch('logn.mission.js', ['checkout.mission.js', 'login.mission.js']))
+      .toBe('login.mission.js');
+  });
+
+  it('resolves selected reports by run id, filename, and direct path', () => {
+    const { resolveReportFile } = __test__;
+    const tmp = makeTempDir('testronaut-selected-report-');
+    const reportDir = path.join(tmp, 'reports');
+    fs.mkdirSync(reportDir);
+    const report = path.join(reportDir, 'run_123.json');
+    fs.writeFileSync(report, '{}');
+
+    expect(resolveReportFile('run_123', reportDir, tmp)).toBe(report);
+    expect(resolveReportFile('run_123.json', reportDir, tmp)).toBe(report);
+    expect(resolveReportFile(report, reportDir, tmp)).toBe(report);
+  });
+
+  it('builds a redacted effective config with source information', () => {
+    const { buildEffectiveConfig } = __test__;
+    const effective = buildEffectiveConfig({
+      provider: 'openai', model: 'gpt-5.6', outputDir: 'artifacts', sessionToken: 'secret',
+    }, '/tmp/project');
+    expect(effective.outputDir).toEqual({ value: '/tmp/project/artifacts', source: 'config' });
+    expect(effective.authenticated).toBe(true);
+    expect(JSON.stringify(effective)).not.toContain('secret');
+  });
+
   it('parses booleans in a tolerant way', () => {
     const { parseBool } = __test__;
     expect(parseBool('true')).toBe(true);

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

@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const cliPath = fileURLToPath(new URL('../../bin/cli.js', import.meta.url));
+const tempDirs = [];
+
+function makeProject() {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'testronaut-cli-integration-'));
+  tempDirs.push(cwd);
+  fs.mkdirSync(path.join(cwd, 'missions'));
+  fs.writeFileSync(path.join(cwd, 'missions', 'login.mission.js'), [
+    'export const tags = ["authentication", "smoke"];',
+    'export function executeMission() { throw new Error("must not execute"); }',
+  ].join('\n'));
+  fs.writeFileSync(path.join(cwd, 'testronaut-config.json'), JSON.stringify({
+    provider: 'openai', model: 'gpt-5.6', outputDir: 'artifacts/reports', sessionToken: 'private',
+  }));
+  return cwd;
+}
+
+function run(cwd, args) {
+  const result = spawnSync(process.execPath, [cliPath, ...args], { cwd, encoding: 'utf8' });
+  if (result.error) throw result.error;
+  return result;
+}
+
+afterEach(() => {
+  while (tempDirs.length) fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+});
+
+describe('CLI inspection commands', () => {
+  it('lists mission tags without executing the mission', () => {
+    const result = run(makeProject(), ['list', '--json']);
+    expect(result.status).toBe(0);
+    expect(JSON.parse(result.stdout).missions).toEqual([
+      { file: 'login.mission.js', tags: ['authentication', 'smoke'] },
+    ]);
+  });
+
+  it('reports effective config without exposing the session token', () => {
+    const result = run(makeProject(), ['config', '--json']);
+    expect(result.status).toBe(0);
+    const output = JSON.parse(result.stdout);
+    expect(output.outputDir.value).toMatch(/artifacts[/\\]reports$/);
+    expect(output.authenticated).toBe(true);
+    expect(result.stdout).not.toContain('private');
+  });
+
+  it('suggests a close mission name and exits nonzero during dry-run', () => {
+    const result = run(makeProject(), ['logn.mission.js', '--dry-run', '--json']);
+    expect(result.status).toBe(1);
+    expect(JSON.parse(result.stdout).missions[0]).toMatchObject({
+      status: 'missing', suggestion: 'login.mission.js',
+    });
+  });
+
+  it('loads project .env values before evaluating mission modules', () => {
+    const cwd = makeProject();
+    fs.writeFileSync(path.join(cwd, '.env'), 'MISSION_DESTINATION=https://example.test\n');
+    fs.writeFileSync(path.join(cwd, 'missions', 'login.mission.js'), [
+      'const destination = process.env.MISSION_DESTINATION;',
+      'export const tags = ["authentication"];',
+      'export async function executeMission() {',
+      '  return { missionName: destination, status: "passed", steps: [] };',
+      '}',
+    ].join('\n'));
+
+    const result = run(cwd, ['--tags', 'authentication', '--json', '--quiet']);
+
+    expect(result.status).toBe(0);
+    expect(JSON.parse(result.stdout).missions[0].missionName).toBe('https://example.test');
+  });
+});

package/tests/binTests/init.test.js

@@ -77,6 +77,9 @@ describe('initializeTestronautProject', () => {
     expect(cfg.initialized).toBe(true);
     expect(cfg.outputDir).toBe('missions/mission_reports');
     expect(typeof cfg.maxTurns).toBe('number');
+    expect(cfg.tags).toEqual([]);
+    expect(cfg.tagMatch).toBe('any');
+    expect(cfg.addTags).toEqual([]);
     expect(cfg.dom?.listItemLimit).toBe(3);
     expect(cfg.resourceGuard?.enabled).toBe(true);
     expect(cfg.humanInput?.enabled).toBe(true);
@@ -95,6 +98,9 @@ describe('initializeTestronautProject', () => {
     // Welcome mission (name depends on your implementation; we check presence in missions/)
     const files = fs.readdirSync(path.join(temp, 'missions'));
     expect(files.some(f => /welcome/i.test(f))).toBe(true);
+    const welcome = fs.readFileSync(path.join(temp, 'missions', 'welcome.mission.js'), 'utf8');
+    expect(welcome).toContain('export const tags = [];');
+    expect(welcome).toContain('tags\n  },');
 
     // Exactly two prompts were asked
     expect(shared.calls).toBe(2);
@@ -112,6 +118,9 @@ describe('initializeTestronautProject', () => {
     const cfg = readJson(path.join(temp, 'testronaut-config.json'));
     expect(cfg.provider).toBe('gemini');
     expect(cfg.model).toBe('gemini-2.5-flash');
+    expect(cfg.tags).toEqual([]);
+    expect(cfg.tagMatch).toBe('any');
+    expect(cfg.addTags).toEqual([]);
     expect(cfg.dom?.listItemLimit).toBe(3);
     expect(cfg.resourceGuard?.enabled).toBe(true);
     expect(cfg.humanInput?.enabled).toBe(true);

package/tests/binTests/initHelpersTests/defaultConfig.test.js

@@ -8,6 +8,9 @@ describe('defaultConfig', () => {
     expect(cfg.outputDir).toBe('missions/mission_reports');
     expect(cfg.projectName).toBe('my-app');
     expect(cfg.maxTurns).toBe(20);
+    expect(cfg.tags).toEqual([]);
+    expect(cfg.tagMatch).toBe('any');
+    expect(cfg.addTags).toEqual([]);
     expect(cfg.dom?.listItemLimit).toBe(3);
     expect(cfg.resourceGuard?.enabled).toBe(true);
     expect(cfg.resourceGuard?.hrefIncludes).toContain('/document/');

package/tests/coreTests/missionDiscovery.test.js

@@ -31,11 +31,11 @@ describe('discoverMissionFiles', () => {
     fs.writeFileSync(path.join(missionsDir, 'beta.txt'), '// ignore');
     fs.mkdirSync(path.join(missionsDir, 'nested'), { recursive: true });
     fs.writeFileSync(path.join(missionsDir, 'nested', 'gamma.mission.js'), '// nested');
-    fs.writeFileSync(path.join(missionsDir, 'delta.mission.ts'), '// ts not included by default');
+    fs.writeFileSync(path.join(missionsDir, 'delta.mission.ts'), '// ts');
 
     const res = await discoverMissionFiles({ cwd: tmp });
     expect(res.root).toBe(path.resolve(tmp, 'missions'));
-    expect(res.files).toEqual(['alpha.mission.js']);
+    expect(res.files).toEqual(['alpha.mission.js', 'delta.mission.ts']);
   });
 
   it('respects missions.root with include patterns', async () => {

package/tests/coreTests/missionLoader.test.js

@@ -0,0 +1,52 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { loadMissionModule } from '../../core/missionLoader.js';
+
+const tempDirs = [];
+
+function makeProject(packageJson) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'testronaut-loader-'));
+  tempDirs.push(dir);
+  if (packageJson) {
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(packageJson));
+  }
+  return dir;
+}
+
+afterEach(() => {
+  while (tempDirs.length) fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+});
+
+describe('loadMissionModule', () => {
+  it.each([
+    ['without a package type', undefined],
+    ['inside a CommonJS project', { type: 'commonjs' }],
+  ])('loads ESM-style .mission.js %s', async (_label, packageJson) => {
+    const dir = makeProject(packageJson);
+    const missionPath = path.join(dir, 'sample.mission.js');
+    fs.writeFileSync(missionPath, 'export const tags = ["smoke"]; export async function executeMission() { return "ok"; }');
+
+    const mission = await loadMissionModule(missionPath);
+
+    expect(mission.tags).toEqual(['smoke']);
+    await expect(mission.executeMission()).resolves.toBe('ok');
+  });
+
+  it('loads a typed .mission.ts file with relative imports', async () => {
+    const dir = makeProject({ type: 'commonjs' });
+    fs.writeFileSync(path.join(dir, 'goal.ts'), 'export const goal: string = "TypeScript works";');
+    const missionPath = path.join(dir, 'sample.mission.ts');
+    fs.writeFileSync(missionPath, [
+      'import { goal } from "./goal.ts";',
+      'export const tags: string[] = ["typescript"];',
+      'export async function executeMission(): Promise<string> { return goal; }',
+    ].join('\n'));
+
+    const mission = await loadMissionModule(missionPath);
+
+    expect(mission.tags).toEqual(['typescript']);
+    await expect(mission.executeMission()).resolves.toBe('TypeScript works');
+  });
+});

package/tests/coreTests/turnLoop.test.js

@@ -78,6 +78,7 @@ vi.mock('../../tools/toolSchema.js', () => ({
     { type: 'function', function: { name: 'screenshot', description: 'take a screenshot', parameters: {} } },
     { type: 'function', function: { name: 'list_local_files', description: 'list files', parameters: {} } },
     { type: 'function', function: { name: 'get_mfa_code', description: 'get mfa', parameters: {} } },
+    { type: 'function', function: { name: 'set_ground_control_state', description: 'set state', parameters: {} } },
   ],
 }));
 
@@ -126,6 +127,7 @@ describe('turnLoop', () => {
   let browser;
 
   beforeEach(() => {
+    delete process.env.TESTRONAUT_SCREENSHOTS;
     browser = {};
     // reset spies and chat mock
     shared.chromeToolSpies.fill.mockClear();
@@ -136,6 +138,19 @@ describe('turnLoop', () => {
     if (shared.chatMock) shared.chatMock.mockReset();
   });
 
+  it('does not expose the screenshot tool when screenshots are disabled', async () => {
+    process.env.TESTRONAUT_SCREENSHOTS = '0';
+    shared.chatMock.mockResolvedValueOnce({
+      message: { role: 'assistant', content: 'FINAL: done' },
+      usage: { total_tokens: 2 },
+    });
+
+    await turnLoop(browser, baseMessages(), 1, 0, 0, {}, { steps: [], missionName: 'demo' });
+
+    const tools = shared.chatMock.mock.calls[0][0].tools;
+    expect(tools.map(tool => tool.function.name)).not.toContain('screenshot');
+  });
+
   it('handles a final response in a single turn (no tools)', async () => {
     shared.chatMock.mockResolvedValueOnce({
       message: { role: 'assistant', content: 'FINAL: success' },
@@ -193,6 +208,31 @@ describe('turnLoop', () => {
     expect(step2.result).toMatch(/Success/);
   });
 
+  it('handles Ground Control state locally without dispatching it as a browser tool', async () => {
+    shared.chatMock.mockResolvedValueOnce({
+      message: {
+        role: 'assistant', content: '', tool_calls: [{
+          id: 'tool_gc', type: 'function', function: {
+            name: 'set_ground_control_state',
+            arguments: JSON.stringify({ app: { baseUrl: 'https://example.com' }, session: { loggedIn: false } }),
+          },
+        }],
+      },
+      usage: { total_tokens: 4 },
+    });
+    shared.chatMock.mockResolvedValueOnce({
+      message: { role: 'assistant', content: 'FINAL: done' }, usage: { total_tokens: 2 },
+    });
+
+    const ctx = { steps: [], missionName: 'demo' };
+    const res = await turnLoop(browser, baseMessages(), 2, 0, 0, {}, ctx);
+
+    expect(res.success).toBe(true);
+    expect(ctx.groundControl.app.baseUrl).toBe('https://example.com');
+    expect(ctx.groundControl.session.loggedIn).toBe(false);
+    expect(res.steps[0].events).toContain('[tool ] ← set_ground_control_state result: ✅ Success');
+  });
+
   it('retries a turn on tool error before marking issues', async () => {
     // First turn: tool call → click_text will throw
     shared.chatMock.mockResolvedValueOnce({

package/tests/toolsTests/generateHtmlReport.test.js

@@ -21,11 +21,13 @@ describe('generateHtmlReport', () => {
   it('writes an HTML report containing mission and retry metadata', () => {
     const report = {
       runId: 'run_test',
+      cli: { version: '1.7.0' },
       missions: [
         {
           missionName: 'Mission A',
           submissionType: 'mission',
           submissionName: 'Main',
+          file: 'missions/login.mission.ts',
           status: 'passed',
           tags: ['smoke'],
           steps: [
@@ -57,6 +59,8 @@ describe('generateHtmlReport', () => {
     expect(html).toContain('⚠️ Turn Issues');
     expect(html).toContain('data-tag="smoke"');
     expect(html).toContain('data-tags="smoke"');
+    expect(html).toContain('CLI version:</strong> 1.7.0');
+    expect(html).toContain('missions/login.mission.ts');
     expect(html).toContain('data-tag="untagged"');
     expect(html).toContain('id="match-count"');
     expect(html).toContain('No missions match these tags');

package/tools/chromeBrowser.js

@@ -26,7 +26,7 @@ import { requestHumanInput } from './humanInput.js';
 import { getMfaCode } from './mfaCode.js';
 
 const FILES_DIR = path.join('missions', 'files');
-const REPORTS_DIR = path.join('missions', 'mission_reports');
+const REPORTS_DIR = process.env.TESTRONAUT_OUTPUT_DIR || path.join('missions', 'mission_reports');
 const FILES_LOG = path.join(REPORTS_DIR, 'files.jsonl');
 
 function ensureDir(p) {
@@ -752,7 +752,11 @@ export class ChromeBrowser {
     }
     if (!chosen) {
       await this._debugClickableSnapshot({ scope }).catch(()=>{});
-      await this.page.screenshot({ path: 'missions/mission_reports/screenshots/click_fail.png' }).catch(()=>{});
+      if (process.env.TESTRONAUT_SCREENSHOTS !== '0') {
+        const failurePath = path.join(REPORTS_DIR, 'screenshots', process.env.TESTRONAUT_RUN_ID || '', 'click_fail.png');
+        ensureDir(path.dirname(failurePath));
+        await this.page.screenshot({ path: failurePath }).catch(()=>{});
+      }
       throw new Error('No clickable locator became ready');
     }
     // do the click (standard → hover+click → JS click)
@@ -1183,13 +1187,19 @@ export class ChromeBrowser {
   }
 
   async screenshot({ name = 'screenshot' }) {
+    if (process.env.TESTRONAUT_SCREENSHOTS === '0') {
+      throw new Error('Screenshots are disabled for this run (--no-screenshots).');
+    }
     const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const screenshotPath = `missions/mission_reports/screenshots/${name}_${timestamp}.png`;
+    const screenshotDir = path.join(REPORTS_DIR, 'screenshots', process.env.TESTRONAUT_RUN_ID || '');
+    const screenshotPath = path.join(screenshotDir, `${name}_${timestamp}.png`);
+    ensureDir(screenshotDir);
   
     await this.page.screenshot({ path: screenshotPath });
   
     // ✅ Return relative path for HTML report
-    return `Screenshot saved at: ./screenshots/${name}_${timestamp}.png`;
+    const reportRelativePath = path.relative(REPORTS_DIR, screenshotPath).split(path.sep).join('/');
+    return `Screenshot saved at: ./${reportRelativePath}`;
   }
   
   async upload_file({ selector, fileName, useChooser = false, timeoutMs = 15000 }) {

package/tools/generateHtmlReport.js

@@ -27,7 +27,7 @@ import { normalizeTags } from '../core/tags.js';
  * @returns {string} absolute path to the written HTML file
  */
 export function generateHtmlReport(report, outputPath) {
-  const { runId, startTime, endTime, missions = [], summary = {}, llm = {} } = report;
+  const { runId, startTime, endTime, missions = [], summary = {}, llm = {}, cli = {} } = report;
   const reportTags = normalizeTags(report.tags ?? missions.flatMap(m => m.submissionType === 'mission' ? (m.tags ?? []) : []));
   const durationSec =
     (startTime && endTime)
@@ -137,10 +137,13 @@ export function generateHtmlReport(report, outputPath) {
   const missionGroupBlock = (missionName, subs) => {
     const status = groupStatus(subs);
     const totalSteps = subs.reduce((n, s) => n + (Array.isArray(s.steps) ? s.steps.length : 0), 0);
-    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 startTimes = subs.map(s => s.startTime || 0).filter(Boolean);
+    const endTimes = subs.map(s => s.endTime || 0).filter(Boolean);
+    const firstStart = startTimes.length ? Math.min(...startTimes) : null;
+    const lastEnd = endTimes.length ? Math.max(...endTimes) : null;
+    const groupDur = (firstStart != null && lastEnd != null) ? ((lastEnd - firstStart) / 1000).toFixed(2) : '—';
     const tags = normalizeTags(subs.flatMap(s => s.submissionType === 'mission' ? (s.tags ?? []) : []));
+    const sourceFiles = [...new Set(subs.map(s => s.file).filter(Boolean))];
 
     // pre → mission → post
     const order = { premission: 0, mission: 1, postmission: 2 };
@@ -155,7 +158,7 @@ export function generateHtmlReport(report, outputPath) {
           <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="meta">${sourceFiles.length ? `${sourceFiles.map(esc).join(', ')} • ` : ''}submissions: ${subs.length} • steps: ${totalSteps} • duration: ${groupDur}s</span>
           <span class="toolbar">
             <button class="btn-mini toggle" data-scope="mission" aria-label="Expand">▼</button>
           </span>
@@ -350,6 +353,7 @@ export function generateHtmlReport(report, outputPath) {
       <div><strong>Start:</strong> ${esc(startTime ?? '—')}</div>
       <div><strong>End:</strong> ${esc(endTime ?? '—')} • <strong>Duration:</strong> ${durationSec}s</div>
       <div><strong>LLM:</strong> ${esc(llm.provider ?? '—')} • <strong>Model:</strong> ${esc(llm.model ?? '—')}</div>
+      <div><strong>CLI version:</strong> ${esc(cli.version ?? '—')}</div>
     </div>
   </div>
 

package/tools/mfaCode.js

@@ -9,7 +9,10 @@ export const DEV_API_BASE = 'https://staging.api.testronaut.app';
 
 const MIN_REMAINING_SECONDS = 5;
 const MAX_REMAINING_SECONDS = 25;
-const API_DEBUG_LOG_RELATIVE_PATH = 'missions/mission_reports/api-debug.log';
+const API_DEBUG_LOG_RELATIVE_PATH = path.join(
+  process.env.TESTRONAUT_OUTPUT_DIR || 'missions/mission_reports',
+  'api-debug.log'
+);
 const REDACTED = '<redacted>';
 
 const SENSITIVE_LOG_KEYS = new Set([