testronaut 1.12.1 → 2.0.0

package/.github/workflows/periapsis-vulnerability-exception-request.yml

@@ -24,6 +24,9 @@ on:
       severities:
         description: "Comma-separated severities"
         required: true
+      adjustedSeverity:
+        description: "Optional re-rated severity (alert type only, must be lower than severities)"
+        required: false
       reason:
         description: "Reason for exception"
         required: true
@@ -57,6 +60,7 @@ jobs:
           INPUT_ECOSYSTEM: ${{ inputs.ecosystem }}
           INPUT_SCOPE: ${{ inputs.dependencyScope }}
           INPUT_SEVERITIES: ${{ inputs.severities }}
+          INPUT_ADJUSTED_SEVERITY: ${{ inputs.adjustedSeverity }}
           INPUT_REASON: ${{ inputs.reason }}
           INPUT_UNTIL: ${{ inputs.acceptedUntil }}
           INPUT_APPROVED_BY: ${{ inputs.approvedBy }}
@@ -71,6 +75,7 @@ jobs:
             ${INPUT_ECOSYSTEM:+--ecosystem "$INPUT_ECOSYSTEM"} \
             ${INPUT_SCOPE:+--dependency-scope "$INPUT_SCOPE"} \
             --severities "$INPUT_SEVERITIES" \
+            ${INPUT_ADJUSTED_SEVERITY:+--adjusted-severity "$INPUT_ADJUSTED_SEVERITY"} \
             --reason "$INPUT_REASON" \
             --accepted-until "$INPUT_UNTIL" \
             --approved-by "$INPUT_APPROVED_BY" \
@@ -81,6 +86,16 @@ jobs:
         uses: peter-evans/create-pull-request@v6
         with:
           commit-message: "Add vulnerability SLA exception"
-          title: "Add vulnerability SLA exception"
-          body: "Adds a structured Periapsis vulnerability exception. Review required before merge."
-          branch: "periapsis/vulnerability-exception-request"
+          title: "Add vulnerability SLA exception (${{ inputs.exceptionType }}${{ inputs.alertNumber && format(' #{0}', inputs.alertNumber) || '' }})"
+          body: |
+            Adds a structured Periapsis vulnerability exception. Review required before merge.
+
+            - Type: ${{ inputs.exceptionType }}
+            - Alert: ${{ inputs.alertNumber || 'n/a' }}
+            - Severities: ${{ inputs.severities }}
+            - Adjusted severity: ${{ inputs.adjustedSeverity || 'n/a' }}
+            - Accepted until: ${{ inputs.acceptedUntil }}
+            - Evidence: ${{ inputs.evidenceRef }}
+
+            Reason: ${{ inputs.reason }}
+          branch: "periapsis/vulnerability-exception-${{ github.run_id }}"

package/.github/workflows/periapsis-vulnerability-triage.yml

@@ -0,0 +1,111 @@
+name: Periapsis Vulnerability Triage
+
+on:
+  schedule:
+    - cron: "30 14 * * *"
+  workflow_dispatch:
+    inputs:
+      alertNumber:
+        description: "Dependabot alert number (leave empty to triage pending alerts per policy.triage.automation)"
+        required: false
+      mode:
+        description: "Use the policy's triage.mode, or override it for this run"
+        required: false
+        type: choice
+        default: policy
+        options: [policy, recommend, apply]
+
+permissions:
+  contents: write # commit applied adjustments for the exception PR
+  pull-requests: write # open the exception PR
+  vulnerability-alerts: read
+  actions: write # restore the triage ledger artifact; single-alert apply dispatches the exception request
+
+# The ledger is read at the start and written at the end of each run; never run two at once.
+concurrency:
+  group: periapsis-vulnerability-triage
+  cancel-in-progress: false
+
+jobs:
+  periapsis-vulnerability-triage:
+    runs-on: ubuntu-latest
+    env:
+      SMTP_CONFIGURED: ${{ secrets.PERIAPSIS_SMTP_HOST != '' }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install periapsis
+        run: npm install -g periapsis
+      - name: Restore triage ledger
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          ID=$(gh api "repos/$GITHUB_REPOSITORY/actions/artifacts?name=periapsis-triage-ledger&per_page=1" --jq '.artifacts[0] | select(.expired == false) | .id' || true)
+          if [ -n "$ID" ]; then
+            mkdir -p policy/triage
+            gh api "repos/$GITHUB_REPOSITORY/actions/artifacts/$ID/zip" > "$RUNNER_TEMP/ledger.zip"
+            unzip -o "$RUNNER_TEMP/ledger.zip" -d policy/triage
+            echo "Restored triage ledger from artifact $ID"
+          else
+            echo "No previous triage ledger found; starting fresh"
+          fi
+      - name: Triage vulnerability alerts
+        id: triage
+        run: |
+          ARGS=()
+          if [ -n "$ALERT_NUMBER" ]; then ARGS+=(--alert "$ALERT_NUMBER"); else ARGS+=(--pending); fi
+          if [ -n "$MODE" ] && [ "$MODE" != "policy" ]; then ARGS+=(--mode "$MODE"); fi
+          periapsis vulnerability triage "${ARGS[@]}"
+        env:
+          ALERT_NUMBER: ${{ inputs.alertNumber }}
+          MODE: ${{ inputs.mode }}
+          GITHUB_TOKEN: ${{ secrets.PERIAPSIS_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+          PERIAPSIS_LLM_PROVIDER: ${{ vars.PERIAPSIS_LLM_PROVIDER }}
+          PERIAPSIS_LLM_MODEL: ${{ vars.PERIAPSIS_LLM_MODEL }}
+          PERIAPSIS_LLM_API_KEY: ${{ secrets.PERIAPSIS_LLM_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+          PERIAPSIS_SLACK_WEBHOOK: ${{ secrets.PERIAPSIS_SLACK_WEBHOOK }}
+      - name: Save triage ledger
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: periapsis-triage-ledger
+          path: policy/triage/ledger.json
+          if-no-files-found: ignore
+          retention-days: 90
+      - name: Upload triage reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: vulnerability-triage-${{ github.run_id }}
+          path: |
+            policy/triage/
+            !policy/triage/ledger.json
+          if-no-files-found: ignore
+          retention-days: 90
+      - name: Validate applied adjustments
+        if: steps.triage.outputs.applied != '' && steps.triage.outputs.applied != '0'
+        run: periapsis vulnerability validate
+      - name: Open exception PR for applied adjustments
+        if: steps.triage.outputs.applied != '' && steps.triage.outputs.applied != '0'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          add-paths: policy/vulnerability-exceptions.json
+          commit-message: "Add Periapsis triage severity adjustments"
+          title: "Periapsis triage: ${{ steps.triage.outputs.applied }} severity adjustment(s)"
+          body-path: policy/triage/digest.md
+          branch: "periapsis/triage-adjustments-${{ github.run_id }}"
+      - name: Send triage email
+        if: always() && steps.triage.outputs.email == 'true' && env.SMTP_CONFIGURED == 'true'
+        uses: dawidd6/action-send-mail@v3
+        with:
+          server_address: ${{ secrets.PERIAPSIS_SMTP_HOST }}
+          server_port: ${{ secrets.PERIAPSIS_SMTP_PORT || 587 }}
+          username: ${{ secrets.PERIAPSIS_SMTP_USER }}
+          password: ${{ secrets.PERIAPSIS_SMTP_PASSWORD }}
+          subject: ${{ steps.triage.outputs.subject }}
+          to: ${{ secrets.PERIAPSIS_EMAIL_TO }}
+          from: ${{ secrets.PERIAPSIS_EMAIL_FROM || secrets.PERIAPSIS_SMTP_USER }}
+          body: file://${{ steps.triage.outputs.report }}
+          convert_markdown: true

package/README.md

@@ -49,6 +49,10 @@ Includes:
 
 ## 📦 Installation
 
+Testronaut 2.x requires **Node.js 20 or newer**. This is a breaking change from
+Testronaut 1.x because the bundled Playwright runtime no longer supports Node 18.
+Check your runtime with `node --version` before upgrading.
+
 **Global install** (recommended — use `testronaut` directly):
 ```bash
 npm install -g testronaut
@@ -230,6 +234,10 @@ testronaut upload run_1788745106444
 testronaut upload run_1788745106444.json --no-upload-screenshots
 ```
 
+The local HTML report stays focused on inspecting one run without a service
+dependency. Upload a report to Mission Control for filterable per-mission and
+per-turn token, estimated-cost, and duration charts, including cumulative views.
+
 Chain missions together:
 ```js
 await runMissions({

package/TODO.md

@@ -9,6 +9,10 @@
 - [ ] 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.
 
+## Browser Automation Follow-Ups
+
+- [ ] Fix `click_text` so it prioritizes exact-text actionable elements (`button`, `a`, and elements with interactive roles) instead of clicking the first container whose descendant text includes the target. Define an explicit fallback for partial matches and add regression tests covering nested containers, duplicate labels, hidden elements, and the Add, Logout, and Report failures observed in the examples run.
+
 ## Session and Reporting Follow-Ups
 
 - [ ] Evaluate a true shared browser-context mode for suites that require session storage or in-memory application state; define page reset, crash recovery, and concurrency behavior first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testronaut",
-  "version": "1.12.1",
+  "version": "2.0.0",
   "main": "./runner/testronaut.js",
   "bin": {
     "testronaut": "bin/cli.js"
@@ -11,6 +11,9 @@
     "./runner/testronaut": "./runner/testronaut.js"
   },
   "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "benchmark:optimization": "node ./experiments/optimizationBenchmark.js",
     "benchmark:cross-provider": "node ./experiments/crossProviderBenchmark.js",
@@ -38,7 +41,7 @@
     "jiti": "^2.7.0",
     "node-fetch": "^3.3.2",
     "openai": "^6.39.0",
-    "playwright": "^1.54.1",
+    "playwright": "^1.63.0",
     "prompts": "^2.4.2"
   },
   "keywords": [
@@ -56,7 +59,7 @@
   ],
   "devDependencies": {
     "@types/node": "^26.5.0",
-    "periapsis": "^2.0.1",
+    "periapsis": "^2.1.2",
     "vitest": "^4.1.11"
   },
   "homepage": "https://testronaut.app"

package/policy/vulnerability-policy.json

@@ -29,5 +29,35 @@
     "allowPackageScope": true,
     "allowRepoWideScope": true,
     "allowOrgWideScope": false
+  },
+  "triage": {
+    "mode": "recommend",
+    "notify": [
+      "slack",
+      "email"
+    ],
+    "apply": {
+      "minimumConfidence": "high",
+      "minimumConfidenceSingleStep": "medium",
+      "allowedReachability": [
+        "not_reachable",
+        "potentially_reachable"
+      ],
+      "approvedBy": [
+        "periapsis-triage"
+      ],
+      "workflow": "periapsis-vulnerability-exception-request.yml",
+      "ref": null
+    },
+    "automation": {
+      "minimumSeverity": "high",
+      "scopes": [
+        "runtime",
+        "development"
+      ],
+      "maxTriagesPerRun": 10,
+      "retriageAfterDays": 30,
+      "skipAlerts": []
+    }
   }
-}
+}

package/tests/dependencyCompatibility.test.js

@@ -0,0 +1,22 @@
+import fs from 'fs';
+import path from 'path';
+import { describe, expect, it } from 'vitest';
+
+const root = path.resolve(import.meta.dirname, '..');
+const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+const lock = JSON.parse(fs.readFileSync(path.join(root, 'package-lock.json'), 'utf8'));
+
+describe('runtime dependency compatibility', () => {
+  it('declares the Node runtime required by the installed Playwright version', () => {
+    const playwright = lock.packages['node_modules/playwright'];
+    expect(pkg.engines.node).toBe('>=20');
+    expect(playwright.engines.node).toBe('>=20');
+  });
+
+  it('keeps the manifest, lockfile root, and installed Playwright versions aligned', () => {
+    expect(pkg.dependencies.playwright).toBe('^1.63.0');
+    expect(lock.packages[''].dependencies.playwright).toBe(pkg.dependencies.playwright);
+    expect(lock.packages['node_modules/playwright'].version).toBe('1.63.0');
+    expect(lock.packages['node_modules/playwright-core'].version).toBe('1.63.0');
+  });
+});

package/tests/toolsTests/generateHtmlReport.test.js

@@ -18,6 +18,23 @@ afterEach(() => {
 });
 
 describe('generateHtmlReport', () => {
+  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');
+    generateHtmlReport(report, outPath);
+    const html = fs.readFileSync(outPath, 'utf8');
+    expect(html).toContain('Need deeper analytics?');
+    expect(html).toContain('filtered and cumulative token, estimated-cost, and duration charts');
+    expect(html).toContain('testronaut upload run_analytics_123');
+    expect(html).toContain('aria-label="Copy upload command"');
+    expect(html).toContain("navigator.clipboard.writeText(command)");
+    expect(html).toContain('id="analytics-toggle" aria-expanded="true"');
+    expect(html).toContain("card.classList.toggle('collapsed', expanded)");
+    expect(html).toContain('href="https://mission.testronaut.app/"');
+    expect(html).toContain('href="https://docs.testronaut.app/docs/category/reports-and-mission-control"');
+    expect(html.indexOf('<aside class="analytics-cta">')).toBeLessThan(html.indexOf('<div class="summary">'));
+  });
+
   it('renders explicit suite, mission, and turn durations', () => {
     const report = {
       runId: 'timed_run',

package/tests/toolsTests/playwrightSetup.test.js

@@ -0,0 +1,69 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ensureBrowsers } from '../../tools/playwrightSetup.js';
+
+const tempDirs = [];
+
+afterEach(() => {
+  delete process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD;
+  while (tempDirs.length) fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+});
+
+function tempProject(lockfile) {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'testronaut-playwright-'));
+  tempDirs.push(cwd);
+  if (lockfile) fs.writeFileSync(path.join(cwd, lockfile), '');
+  return cwd;
+}
+
+describe('Playwright browser setup', () => {
+  it('installs the browser matching the locally resolved Playwright version', async () => {
+    const runCommand = vi.fn().mockResolvedValue(undefined);
+    const cliPath = '/project/node_modules/playwright/cli.js';
+
+    await ensureBrowsers(
+      { browser: 'chromium', withDeps: true },
+      { getInstallation: () => ({ version: '1.63.0', cliPath }), runCommand, cwd: tempProject('package-lock.json') },
+    );
+
+    expect(runCommand).toHaveBeenCalledOnce();
+    expect(runCommand).toHaveBeenCalledWith(
+      process.execPath,
+      [cliPath, 'install', 'chromium', '--with-deps'],
+      { PLAYWRIGHT_BROWSERS_PATH: '0' },
+    );
+  });
+
+  it.each([
+    ['pnpm-lock.yaml', 'pnpm', ['exec', 'playwright', 'install', 'chromium']],
+    ['yarn.lock', 'yarn', ['playwright', 'install', 'chromium']],
+    ['bun.lockb', 'bunx', ['playwright', 'install', 'chromium']],
+    ['package-lock.json', 'npm', ['exec', '--yes', '--', 'playwright', 'install', 'chromium']],
+  ])('uses the project package manager fallback for %s', async (lockfile, command, args) => {
+    const runCommand = vi.fn()
+      .mockRejectedValueOnce(new Error('npx unavailable'))
+      .mockResolvedValueOnce(undefined);
+
+    await ensureBrowsers(
+      { browser: 'chromium', withDeps: false },
+      {
+        getInstallation: () => ({ version: '1.63.0', cliPath: '/project/node_modules/playwright/cli.js' }),
+        runCommand,
+        cwd: tempProject(lockfile),
+      },
+    );
+
+    expect(runCommand).toHaveBeenNthCalledWith(2, command, args, { PLAYWRIGHT_BROWSERS_PATH: '0' });
+  });
+
+  it('does not invoke an installer when browser downloads are disabled', async () => {
+    process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD = '1';
+    const runCommand = vi.fn();
+
+    await ensureBrowsers({}, { getInstallation: vi.fn(), runCommand, cwd: tempProject() });
+
+    expect(runCommand).not.toHaveBeenCalled();
+  });
+});

package/tools/generateHtmlReport.js

@@ -308,6 +308,7 @@ export function generateHtmlReport(report, outputPath) {
     /* ===== Header ===== */
     .header{ max-width:960px; margin:0 auto 16px; padding:22px 24px; position:relative; overflow:hidden; }
     .header::after{content:"";position:absolute;right:0;top:0;width:92px;height:4px;background:linear-gradient(90deg,var(--orange),var(--amber));}
+    .header-layout{display:grid;grid-template-columns:minmax(0,1fr) minmax(280px,340px);gap:22px;align-items:start;}
     .eyebrow{margin-bottom:7px;color:var(--cyan);font-size:11px;font-weight:800;letter-spacing:.18em;text-transform:uppercase;}
     h1{ margin:0 0 12px; font-size:27px; font-weight:850; color:#fff; letter-spacing:-.02em; }
     .run-meta{ color:var(--text-muted); display:grid; gap:4px; }
@@ -341,7 +342,7 @@ export function generateHtmlReport(report, outputPath) {
     .filter-empty{max-width:928px;margin:12px auto;padding:28px 16px;text-align:center;border:1px dashed var(--hairline-strong);border-radius:16px;color:var(--text-muted);}
     .filter-empty strong{display:block;color:var(--text);font-size:18px;margin-bottom:6px;}
     .mission-group.nonmatching{opacity:.45;}
-    @media(max-width:640px){.match-count{width:100%;margin-left:0}.tag-filter{padding:14px 12px}.meta{display:none}}
+    @media(max-width:760px){.header-layout{grid-template-columns:1fr}.match-count{width:100%;margin-left:0}.tag-filter{padding:14px 12px}.meta{display:none}}
 
     /* ===== Disclosure blocks ===== */
     details{ background: var(--panel); border:1px solid var(--hairline); border-radius:16px; margin:10px 0; overflow:hidden; }
@@ -420,19 +421,76 @@ export function generateHtmlReport(report, outputPath) {
     /* container width */
     .container{ max-width:960px; margin:0 auto; }
     .empty{ color: var(--text-muted); padding:12px; }
+    .analytics-cta{
+      padding:16px; background:rgba(2,6,23,.34); border:1px solid var(--hairline-strong);
+      border-radius:13px;
+      color:var(--text-muted); font-size:13px;
+    }
+    .analytics-toggle{
+      width:100%;padding:0;display:flex;align-items:center;justify-content:space-between;gap:12px;
+      color:var(--text);background:transparent;border:0;cursor:pointer;text-align:left;font:inherit;font-weight:800;
+    }
+    .analytics-toggle svg{width:16px;height:16px;fill:none;stroke:currentColor;stroke-width:2;transition:transform .18s ease;}
+    .analytics-cta.collapsed .analytics-toggle svg{transform:rotate(-90deg);}
+    .analytics-body{display:grid;gap:11px;margin-top:11px;}
+    .analytics-cta.collapsed .analytics-body{display:none;}
+    .analytics-cta code{
+      color:#bfdbfe; background:rgba(59,130,246,.12); border:1px solid rgba(96,165,250,.25);
+      border-radius:8px; padding:6px 9px; white-space:nowrap;
+    }
+    .upload-command{display:flex;align-items:stretch;min-width:0;}
+    .upload-command code{flex:1;min-width:0;overflow:auto;border-radius:8px 0 0 8px;}
+    .copy-command{
+      display:grid;place-items:center;width:36px;flex:none;cursor:pointer;color:#bfdbfe;
+      background:rgba(59,130,246,.18);border:1px solid rgba(96,165,250,.32);border-left:0;
+      border-radius:0 8px 8px 0;
+    }
+    .copy-command:hover,.copy-command.copied{color:#fff;background:rgba(59,130,246,.3);}
+    .copy-command svg{width:16px;height:16px;fill:none;stroke:currentColor;stroke-width:1.8;}
+    .sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;}
+    .analytics-links{display:flex;gap:8px;flex-wrap:wrap;}
+    .analytics-links a{
+      color:#bfdbfe;text-decoration:none;border:1px solid rgba(96,165,250,.32);
+      background:rgba(59,130,246,.12);border-radius:999px;padding:6px 10px;font-size:12px;font-weight:750;
+    }
+    .analytics-links a:hover{background:rgba(59,130,246,.22);}
   </style>
 </head>
 <body>
   <div class="header glass">
-    <div class="eyebrow">Mission Control · Flight Report</div>
-    <h1>🧑‍🚀 <span class="gradient-text">Testronaut Report</span></h1>
-    <div class="run-meta">
-      <div class="provider-meta"><span class="provider-logo" title="${esc(provider.name)}" aria-label="${esc(provider.name)}">${provider.logo}</span><strong>${esc((reportModels.length ? reportModels : [llm.model ?? '—']).join(' + '))}</strong>${reportJevUsage.evaluations ? ` <span aria-hidden="true">+</span> <span class="provider-logo" title="Jev" aria-label="Jev">${jevLogo}</span><strong>Jev</strong>` : ''}</div>
-      <div><strong>Run ID:</strong> ${esc(runId ?? '—')}</div>
-      <div><strong>Start:</strong> ${esc(startTime ?? '—')}</div>
-      <div><strong>End:</strong> ${esc(endTime ?? '—')}</div>
-      <div><strong>Duration:</strong> ${durationSec}s</div>
-      <div><strong>CLI version:</strong> ${esc(cli.version ?? '—')}</div>
+    <div class="header-layout">
+      <div>
+        <div class="eyebrow">Mission Control · Flight Report</div>
+        <h1>🧑‍🚀 <span class="gradient-text">Testronaut Report</span></h1>
+        <div class="run-meta">
+          <div class="provider-meta"><span class="provider-logo" title="${esc(provider.name)}" aria-label="${esc(provider.name)}">${provider.logo}</span><strong>${esc((reportModels.length ? reportModels : [llm.model ?? '—']).join(' + '))}</strong>${reportJevUsage.evaluations ? ` <span aria-hidden="true">+</span> <span class="provider-logo" title="Jev" aria-label="Jev">${jevLogo}</span><strong>Jev</strong>` : ''}</div>
+          <div><strong>Run ID:</strong> ${esc(runId ?? '—')}</div>
+          <div><strong>Start:</strong> ${esc(startTime ?? '—')}</div>
+          <div><strong>End:</strong> ${esc(endTime ?? '—')}</div>
+          <div><strong>Duration:</strong> ${durationSec}s</div>
+          <div><strong>CLI version:</strong> ${esc(cli.version ?? '—')}</div>
+        </div>
+      </div>
+      <aside class="analytics-cta">
+        <button type="button" class="analytics-toggle" id="analytics-toggle" aria-expanded="true" aria-controls="analytics-body">
+          <span>Need deeper analytics?</span>
+          <svg viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg>
+        </button>
+        <div class="analytics-body" id="analytics-body">
+          <span>Upload this run for filtered and cumulative token, estimated-cost, and duration charts.</span>
+          <div class="upload-command">
+            <code id="analytics-upload-command">testronaut upload ${esc(runId ?? '')}</code>
+            <button type="button" class="copy-command" id="copy-upload-command" aria-label="Copy upload command" title="Copy upload command">
+              <svg viewBox="0 0 24 24" aria-hidden="true"><rect x="9" y="9" width="11" height="11" rx="2"/><path d="M15 9V6a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v7a2 2 0 0 0 2 2h3"/></svg>
+            </button>
+            <span class="sr-only" id="copy-upload-status" aria-live="polite"></span>
+          </div>
+          <div class="analytics-links">
+            <a href="https://mission.testronaut.app/">Open Mission Control</a>
+            <a href="https://docs.testronaut.app/docs/category/reports-and-mission-control">Upload guide</a>
+          </div>
+        </div>
+      </aside>
     </div>
   </div>
 
@@ -475,6 +533,50 @@ export function generateHtmlReport(report, outputPath) {
   </div>
   <script>
   (function () {
+    var analyticsToggle = document.getElementById('analytics-toggle');
+    var analyticsBody = document.getElementById('analytics-body');
+    if (analyticsToggle && analyticsBody) {
+      analyticsToggle.addEventListener('click', function () {
+        var card = analyticsToggle.closest('.analytics-cta');
+        var expanded = analyticsToggle.getAttribute('aria-expanded') === 'true';
+        analyticsToggle.setAttribute('aria-expanded', expanded ? 'false' : 'true');
+        analyticsBody.hidden = expanded;
+        if (card) card.classList.toggle('collapsed', expanded);
+      });
+    }
+    var copyUploadButton = document.getElementById('copy-upload-command');
+    var uploadCommand = document.getElementById('analytics-upload-command');
+    var copyUploadStatus = document.getElementById('copy-upload-status');
+    if (copyUploadButton && uploadCommand) {
+      copyUploadButton.addEventListener('click', function () {
+        var command = uploadCommand.textContent || '';
+        var copy = navigator.clipboard && window.isSecureContext
+          ? navigator.clipboard.writeText(command)
+          : new Promise(function (resolve, reject) {
+              var input = document.createElement('textarea');
+              input.value = command;
+              input.setAttribute('readonly', '');
+              input.style.position = 'fixed';
+              input.style.opacity = '0';
+              document.body.appendChild(input);
+              input.select();
+              try { document.execCommand('copy') ? resolve() : reject(new Error('Copy failed')); }
+              catch (error) { reject(error); }
+              finally { document.body.removeChild(input); }
+            });
+        copy.then(function () {
+          copyUploadButton.classList.add('copied');
+          copyUploadButton.title = 'Copied!';
+          if (copyUploadStatus) copyUploadStatus.textContent = 'Upload command copied';
+          window.setTimeout(function () {
+            copyUploadButton.classList.remove('copied');
+            copyUploadButton.title = 'Copy upload command';
+          }, 1600);
+        }).catch(function () {
+          if (copyUploadStatus) copyUploadStatus.textContent = 'Could not copy upload command';
+        });
+      });
+    }
     var selectedTags = [];
     function applyTagFilter() {
       var match = document.getElementById('tag-match');

package/tools/playwrightSetup.js

@@ -1,23 +1,22 @@
 import { createRequire } from 'module';
 import fs from 'fs';
 import path from 'path';
-import { promisify } from 'util';
-import { exec as execCb } from 'child_process';
-
-const exec = promisify(execCb);
+import { spawn } from 'child_process';
 
 // Resolve from the **user project** (cwd)
 const req = createRequire(path.join(process.cwd(), 'noop.js'));
 
 // Prefer 'playwright' → '@playwright/test' → 'playwright-core' from the USER PROJECT (cwd)
-function getPlaywrightVersion() {
+function getPlaywrightInstallation() {
   console.log('🔍 Detecting installed Playwright version (from project)…');
   const tryPkg = (name) => {
     try {
       const p = req.resolve(`${name}/package.json`);
-      const v = JSON.parse(fs.readFileSync(p, 'utf8')).version;
-      console.log(`   • found ${name}@${v} → ${p}`);
-      return v;
+      const pkg = JSON.parse(fs.readFileSync(p, 'utf8'));
+      const bin = typeof pkg.bin === 'string' ? pkg.bin : Object.values(pkg.bin || {})[0];
+      const cliPath = bin ? path.resolve(path.dirname(p), bin) : null;
+      console.log(`   • found ${name}@${pkg.version} → ${p}`);
+      return { version: pkg.version, cliPath };
     } catch {
       return null;
     }
@@ -26,7 +25,7 @@ function getPlaywrightVersion() {
     tryPkg('playwright') ||
     tryPkg('@playwright/test') ||
     tryPkg('playwright-core') ||
-    'latest'
+    { version: 'latest', cliPath: null }
   );
 }
 
@@ -38,33 +37,46 @@ function pkgManagerForCwd(cwd = process.cwd()) {
   return 'npm';
 }
 
-async function run(cmd, extraEnv = {}) {
-  console.log(`\n> ${cmd}`);
-  await exec(cmd, { stdio: 'inherit', env: { ...process.env, ...extraEnv } });
+async function run(command, args, extraEnv = {}) {
+  console.log(`\n> ${[command, ...args].join(' ')}`);
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: 'inherit',
+      env: { ...process.env, ...extraEnv },
+    });
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${command} exited with ${signal || `code ${code}`}`));
+    });
+  });
 }
 
-export async function ensureBrowsers({ browser = 'chromium', withDeps = true } = {}) {
+export async function ensureBrowsers(
+  { browser = 'chromium', withDeps = true } = {},
+  { getInstallation = getPlaywrightInstallation, runCommand = run, cwd = process.cwd() } = {},
+) {
   if (process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD === '1') return;
 
-  const version = getPlaywrightVersion();
-  const withDepsFlag = withDeps ? ' --with-deps' : '';
+  const installation = getInstallation();
+  const installArgs = ['install', browser, ...(withDeps ? ['--with-deps'] : [])];
   const localCacheEnv = { PLAYWRIGHT_BROWSERS_PATH: '0' }; // project-local cache
 
-  const npxCmd = `npx -y playwright@${version} install ${browser}${withDepsFlag}`;
   try {
-    await run(npxCmd, localCacheEnv);
+    if (!installation.cliPath) throw new Error('No local Playwright CLI was resolved');
+    // Execute the CLI beside the package that will launch the browser. With
+    // PLAYWRIGHT_BROWSERS_PATH=0, running an npx-temporary CLI downloads into
+    // the temporary package instead of this project and leaves launch broken.
+    await runCommand(process.execPath, [installation.cliPath, ...installArgs], localCacheEnv);
   } catch {
-    const pm =
-      fs.existsSync(path.join(process.cwd(), 'pnpm-lock.yaml')) ? 'pnpm' :
-      fs.existsSync(path.join(process.cwd(), 'yarn.lock')) ? 'yarn' :
-      fs.existsSync(path.join(process.cwd(), 'bun.lockb')) ? 'bun' : 'npm';
+    const pm = pkgManagerForCwd(cwd);
 
-    const fallback =
-      pm === 'pnpm' ? `pnpm exec playwright install ${browser}${withDepsFlag}` :
-      pm === 'yarn' ? `yarn playwright install ${browser}${withDepsFlag}` :
-      pm === 'bun'  ? `bunx playwright install ${browser}${withDepsFlag}` :
-                      `npm exec --yes playwright@${version} install ${browser}${withDepsFlag}`;
+    const [command, args] =
+      pm === 'pnpm' ? ['pnpm', ['exec', 'playwright', ...installArgs]] :
+      pm === 'yarn' ? ['yarn', ['playwright', ...installArgs]] :
+      pm === 'bun'  ? ['bunx', ['playwright', ...installArgs]] :
+                      ['npm', ['exec', '--yes', '--', 'playwright', ...installArgs]];
 
-    await run(fallback, localCacheEnv);
+    await runCommand(command, args, localCacheEnv);
   }
 }