staysfixed 0.7.2 → 0.9.0

package/src/v2/adapters/web-driver.js

@@ -67,43 +67,73 @@ import { globToRegExp } from '../../freeze/network.js';
  */
 
 /**
- * Find Playwright, in the two places it could honestly be.
+ * Find the browser library, in every place it could honestly be.
  *
- * Stays Fixed is installed INTO other people's projects, so "is Playwright here" has two
- * different answers: is it beside us, and is it in the project we were pointed at. Both are
- * tried, because a project that already drives its own tests with Playwright should not be
- * asked to install a second copy.
+ * ## Two packages, not one
  *
- * It is loaded with `import()` rather than named at the top of the file on purpose. A tool
- * that cannot start at all because an optional browser library is missing is a tool that
- * cannot tell you what is missing.
+ * `playwright` and `playwright-core` are the same driver. The difference is that the first
+ * downloads its own copy of Chromium when it installs — about 150MB — and the second
+ * downloads nothing and expects to be told where a browser already is. This tool depends on
+ * `playwright-core` and finds the browser itself, because it already knows how: `browsers.js`
+ * locates Chrome for Testing, Chrome, Edge or Chromium on the machine, and deliberately
+ * prefers one that is not the browser the person actually uses.
+ *
+ * Both names are tried, in both places, because a project that already drives its own tests
+ * with the full `playwright` should never be asked to install a second copy of the same thing.
+ *
+ * ## Why it is loaded like this
+ *
+ * With `import()` rather than named at the top of the file: a tool that cannot start at all
+ * because a browser library is missing is a tool that cannot tell you what is missing.
+ *
+ * ## What went wrong here before, so it does not happen twice
+ *
+ * `playwright` was removed from this package's dependencies on the grounds that nothing in
+ * `src/` imported it. Nothing does — this line does, and a search for a static import cannot
+ * see it. The result shipped: 0.7.2 told every agent that asked that web apps and sites could
+ * be checked "here and now", and then answered every website check with "Playwright is not
+ * installed, so no web page can be opened". A tool that is wrong about its own headline
+ * ability is worse than one that lacks it. `test/v2/web-driver.test.js` now holds the
+ * dependency in place by name.
  *
  * @param {object} [opts]
  * @param {string} [opts.projectRoot]  The project being checked. Looked in second.
  * @returns {Promise<PlaywrightState>}
  */
 export async function loadPlaywright(opts = {}) {
-  const install = 'npm install --save-dev playwright';
+  const install = 'npm install playwright-core';
   /** @type {any} */
   let mod = null;
   /** @type {string|undefined} */
   let version;
+  /** @type {string|null} */
+  let loadedName = null;
 
   /** @param {any} loaded */
   const unwrap = (loaded) => (loaded && loaded.chromium ? loaded : (loaded?.default ?? null));
 
-  try {
-    mod = unwrap(await import('playwright'));
-  } catch {
-    // Not beside us. Try the project we were pointed at.
+  // `playwright` first, because a project that has the full package has a browser downloaded
+  // with it, and using that is one less thing to go looking for.
+  for (const name of ['playwright', 'playwright-core']) {
+    if (mod) break;
+    try {
+      mod = unwrap(await import(name));
+      if (mod) loadedName = name;
+    } catch {
+      // Not beside us under this name. Try the next, then the project we were pointed at.
+    }
   }
 
   if (!mod && opts.projectRoot) {
-    try {
-      const require = createRequire(path.join(opts.projectRoot, 'package.json'));
-      mod = unwrap(await import(require.resolve('playwright')));
-    } catch {
-      // Not there either. That is an answer, and it is reported as one.
+    for (const name of ['playwright', 'playwright-core']) {
+      if (mod) break;
+      try {
+        const require = createRequire(path.join(opts.projectRoot, 'package.json'));
+        mod = unwrap(await import(require.resolve(name)));
+        if (mod) loadedName = name;
+      } catch {
+        // Not there either. That is an answer, and it is reported as one.
+      }
     }
   }
 
@@ -111,14 +141,14 @@ export async function loadPlaywright(opts = {}) {
     return {
       ok: false,
       state: 'no package',
-      why: 'Playwright is not installed, so no web page can be opened. Everything read out of the source still works; nothing that needs a browser does.',
+      why: 'The browser driver is not installed, so no web page can be opened. Everything read out of the source still works; nothing that needs a browser does.',
       howToGet: install,
     };
   }
 
   try {
     const require = createRequire(import.meta.url);
-    version = String(require('playwright/package.json').version);
+    version = String(require(`${loadedName ?? 'playwright-core'}/package.json`).version);
   } catch {
     // A version we cannot read is not a reason to refuse to run.
   }
@@ -131,14 +161,43 @@ export async function loadPlaywright(opts = {}) {
     executable = undefined;
   }
 
-  const there = Boolean(executable) && (await exists(/** @type {string} */ (executable)));
+  let there = Boolean(executable) && (await exists(/** @type {string} */ (executable)));
+
+  // The driver's own browser is not the only browser.
+  //
+  // `playwright-core` downloads nothing, so it always names a Chromium that is not there.
+  // That is not a failure — this tool already knows how to find a browser, and has a
+  // considered opinion about which one: `browsers.js` prefers Chrome for Testing over the
+  // browser the person actually uses, precisely so a check can never take over their
+  // windows, their profile or their sign-ins.
+  //
+  // So: ask it. Only when there is no browser on the machine at all is this a real "no".
+  /** @type {string|undefined} */
+  let borrowedFrom;
+  /** True when the browser found is the one the PERSON uses, not a separate one. */
+  let borrowedTheirOwn = false;
+  if (!there) {
+    try {
+      const { surveyBrowsers } = await import('../browsers.js');
+      const survey = await surveyBrowsers({ headless: true });
+      if (survey.chosen?.binary && (await exists(survey.chosen.binary))) {
+        executable = survey.chosen.binary;
+        borrowedFrom = survey.chosen.name;
+        borrowedTheirOwn = survey.borrowingHis === true || survey.chosen.everyday === true;
+        there = true;
+      }
+    } catch {
+      // Nothing found, or the survey itself would not run. Reported as "no browser" below.
+    }
+  }
+
   if (!there) {
     return {
       ok: false,
       state: 'no browser',
       chromium: mod.chromium,
       version,
-      why: `Playwright ${version ?? ''} is installed but its browser has not been downloaded, so no page can be opened yet. This is one command and nobody has to be asked.`.trim(),
+      why: `The browser driver ${version ?? ''} is installed, and there is no browser on this machine for it to open. This is one command and nobody has to be asked.`.trim(),
       howToGet: 'npx playwright install chromium',
       executable,
     };
@@ -150,10 +209,35 @@ export async function loadPlaywright(opts = {}) {
     chromium: mod.chromium,
     version,
     executable,
-    why: `Playwright ${version ?? ''} is here and its Chromium is downloaded, so pages can be opened.`.trim(),
+    why: browserNote(version, borrowedFrom, borrowedTheirOwn),
   };
 }
 
+/**
+ * What to say about the browser a check will open.
+ *
+ * "a separate application from the browser you use" used to be said whatever was found — and
+ * the one case where that sentence matters is the case where it is false. With no downloaded
+ * test browser anywhere, the survey falls back to the person's OWN browser, and this then
+ * told them the opposite of what was about to happen. A reassurance is only worth anything
+ * if it is withheld when it is not true.
+ *
+ * Exported so the wording is a test rather than a thing somebody has to notice.
+ *
+ * @param {string|undefined} version        The driver version, if it said one.
+ * @param {string|undefined} borrowedFrom   The browser found, if one had to be borrowed.
+ * @param {boolean} borrowedTheirOwn        True when that browser is the person's own.
+ * @returns {string}
+ */
+export function browserNote(version, borrowedFrom, borrowedTheirOwn) {
+  const v = version ?? '';
+  if (!borrowedFrom) return `The browser driver ${v} is here and its Chromium is downloaded, so pages can be opened.`.trim();
+  if (borrowedTheirOwn) {
+    return `The browser driver ${v} is here and the only browser on this machine is the one you use yourself (${borrowedFrom}). It will be opened invisibly with a throwaway profile, so your own settings, cookies and tabs are never touched — but it is your browser, not a separate one. \`npx playwright install chromium\` gives checks one of their own.`.trim();
+  }
+  return `The browser driver ${v} is here and it will open ${borrowedFrom}, which is a separate application from the browser you use, so pages can be opened.`.trim();
+}
+
 /**
  * @param {string} file
  * @returns {Promise<boolean>}
@@ -192,6 +276,7 @@ async function exists(file) {
  *
  * @param {object} opts
  * @param {any} opts.chromium
+ * @param {string} [opts.executable]  Which browser to open. From `loadPlaywright`.
  * @param {string} opts.scratchDir
  * @param {{width: number, height: number, deviceScaleFactor?: number}} [opts.viewport]
  * @param {'light'|'dark'} [opts.colorScheme]
@@ -209,6 +294,15 @@ export async function openWindow(opts) {
   await fsp.mkdir(profileDir, { recursive: true });
 
   const context = await opts.chromium.launchPersistentContext(profileDir, {
+    // Which browser, said out loud rather than left to the driver's default.
+    //
+    // `playwright-core` has no browser of its own, so without this it looks for one that was
+    // never downloaded and the launch fails with a path nobody recognises. `loadPlaywright`
+    // has already decided which browser this machine should open — usually Chrome for
+    // Testing, deliberately not the browser the person uses — and this is where that decision
+    // is honoured. Left out when there is nothing to say, so the full `playwright` keeps
+    // using the Chromium it downloaded for itself.
+    ...(opts.executable ? { executablePath: opts.executable } : {}),
     headless: opts.headed !== true,
     viewport,
     deviceScaleFactor,
@@ -1243,7 +1337,9 @@ export function flattenAria(nodes) {
       // Two things with the same name in the same place have to be told apart somehow, and
       // counting is the only honest way left. The count is kept per place, so it cannot
       // spread: adding a row to one list never renumbers another.
-      const key = `${scope.join(' ')}${node.role}${node.name ?? ''}`;
+      // The separator is written as the escape, never as the byte. A raw NUL makes grep and
+      // file(1) treat this whole module as binary and skip it without saying so.
+      const key = `${scope.join(' ')}\u0000${node.role}\u0000${node.name ?? ''}`;
       const nth = (seen.get(key) ?? 0) + 1;
       seen.set(key, nth);
 
@@ -1419,6 +1515,20 @@ export async function runStep(page, step, opts = {}) {
         break;
     }
   }
+  // A step that did nothing at all is almost always a word this tool does not know, and
+  // saying nothing about it is the worst outcome available: the journey walks on, the sign-in
+  // never happens, every page behind the login wall photographs the login page, and the run
+  // comes back clean. `staysfixed init` itself shipped `{ fill: '#email', with: 'a@b.c' }`
+  // as its sign-in example, and neither word is in the vocabulary.
+  if (did.length === 0) {
+    const known = new Set([...ACTION_ORDER, 'text', 'timeoutMs', 'name', 'note', 'act', 'checkpoint', 'describe']);
+    const unknown = Object.keys(step).filter((k) => !known.has(k));
+    if (unknown.length > 0) {
+      throw new Error(
+        `This step does nothing: ${unknown.map((k) => `\`${k}\``).join(', ')} ${unknown.length === 1 ? 'is not a word' : 'are not words'} this tool knows, so the step was skipped and whatever it was meant to do did not happen. The steps it understands are: ${ACTION_ORDER.join(', ')} — with \`text\` beside \`type\`. To type into a field: { type: '#email', text: 'a@b.c' }.`,
+      );
+    }
+  }
   return did;
 }
 

package/src/v2/adapters/web.js

@@ -36,10 +36,10 @@
  * Every refusal is reported as a hole in the check. None of them is ever reported as a pass.
  */
 
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
 
 import {
   countBucket, defineAdapter, howLongItTook, joinPath, notCovered, observation, sizeBucket,
@@ -49,6 +49,7 @@ import { copyForScratch, frozenEnvironment } from './process.js';
 import { freePort, looksDestructive, waitForServer } from './http.js';
 import { applyFreeze, prepareForShutter } from '../../freeze/index.js';
 import { settle } from '../../freeze/settle.js';
+import { spawnServer, stopServer } from './child.js';
 import {
   actOf, countRoles, flattenAria, inkOf, loadPlaywright, openWindow, parseAria, runStep, short,
   watchTheWire, whereItIs, withLimit,
@@ -70,6 +71,26 @@ const VIEWPORT = { width: 1280, height: 800, deviceScaleFactor: 1 };
 /** Folders that never hold a page worth walking. */
 const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'out', '.next', 'coverage', '.staysfixed']);
 
+/**
+ * Why a folder would not open, in words somebody can act on.
+ *
+ * The code alone is no use to the person who has to fix it: `EACCES` on its own has sent
+ * more than one person looking for a bug in the tool.
+ *
+ * @param {unknown} error
+ * @returns {string}
+ */
+function whyNotOpened(error) {
+  const code = String(/** @type {any} */ (error)?.code ?? '');
+  if (code === 'EACCES' || code === 'EPERM') return 'this account does not have permission to open it';
+  if (code === 'ENOENT') return 'it was there when the walk started and is not there now';
+  if (code === 'ENOTDIR') return 'something in the way is a file, not a folder';
+  if (code === 'ELOOP') return 'the links in it point round in a circle';
+  if (code === 'EMFILE' || code === 'ENFILE') return 'this machine ran out of open files while reading it';
+  const said = String(/** @type {any} */ (error)?.message ?? error ?? '').trim();
+  return said === '' ? 'the reason was not given' : said;
+}
+
 /**
  * The pages a project has, read out of its folder names.
  *
@@ -83,12 +104,29 @@ const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'out', '.nex
  * reported as needing a sample value rather than guessed at, because "we did not check
  * this" and "this is fine" must never be allowed to look alike.
  *
+ * A FOLDER THIS CANNOT OPEN IS NAMED, not skipped. It used to `continue` on the read that
+ * failed, which threw away that folder and every page underneath it without one word — and
+ * a page that was never listed is never walked, never counted, and never missed. The run
+ * then reported that nothing had changed about a section of the site it had not looked at.
+ * This is the same shape of bug as three others that were found and closed elsewhere in the
+ * tool; this was the fourth place it was living.
+ *
  * @param {string} root
+ * @param {{unreadable?: {folder: string, why: string}[]}} [collect]
+ *   Hand in an object and every folder that could not be opened is pushed onto
+ *   `collect.unreadable`, with the reason in plain English. Callers that pass nothing get
+ *   the old shape back and lose the holes, so the two callers inside this file both pass
+ *   one; `detect` turns them into something a person can act on and `journeys` turns them
+ *   into missing coverage, which is what stops a folder nobody could read reading as a
+ *   folder with nothing in it.
  * @returns {Promise<{url: string, file: string, needs: string[]}[]>}
  */
-export async function readPageRoutes(root) {
+export async function readPageRoutes(root, collect = {}) {
   /** @type {Map<string, {url: string, file: string, needs: string[]}>} */
   const found = new Map();
+  const unreadable = collect.unreadable;
+  /** @type {Set<string>} */
+  const alreadySaid = new Set();
 
   /**
    * @param {string} base
@@ -104,7 +142,12 @@ export async function readPageRoutes(root) {
       let entries;
       try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
-      } catch {
+      } catch (error) {
+        const folder = path.relative(root, dir) || '.';
+        if (unreadable && !alreadySaid.has(folder)) {
+          alreadySaid.add(folder);
+          unreadable.push({ folder, why: whyNotOpened(error) });
+        }
         continue;
       }
       for (const entry of entries) {
@@ -163,9 +206,20 @@ export async function readPageRoutes(root) {
  * already has them), a journeys file if one was named, and the pages read out of the folder
  * names for everything neither of those covers. Never invented, never crawled.
  *
+ * TWO SCREENS WITH ONE NAME ARE TWO SCREENS. They used to be one: the list is built in a
+ * Map keyed by name, so the second `set` overwrote the first, and the screen that lost was
+ * never walked, never compared and never counted as a door nobody opened — missing from the
+ * very ledger that exists to catch exactly this. Now the second one is told apart by a
+ * number and both are walked. Two entries that are the same in every respect really are one
+ * screen written down twice, and only those are folded together.
+ *
  * @param {object} input
  * @param {Record<string, any>} input.config
  * @param {{url: string, file: string, needs: string[]}[]} input.pages
+ * @param {{folder: string, why: string}[]} [input.unreadable]
+ *   Folders `readPageRoutes` could not open. Each becomes a journey that says it was not
+ *   walked and why, which the engine records as missing coverage. A page behind one of them
+ *   was never listed, so nothing else in the run would ever mention it.
  * @returns {Journey[]}
  */
 export function journeysFrom(input) {
@@ -173,19 +227,50 @@ export function journeysFrom(input) {
   const samples = config.samples ?? {};
   /** @type {Map<string, Journey>} */
   const journeys = new Map();
+  /** @type {Map<string, string>} name -> what that journey is, so a true duplicate is spotted */
+  const shapes = new Map();
+
+  /**
+   * A name nothing else is using. Numbering rather than overwriting: a screen that is
+   * dropped here is dropped everywhere, silently, for the rest of the run.
+   *
+   * @param {string} wanted
+   * @returns {string}
+   */
+  const freeName = (wanted) => {
+    if (!journeys.has(wanted)) return wanted;
+    for (let n = 2; ; n += 1) {
+      const tried = `${wanted} (${n})`;
+      if (!journeys.has(tried)) return tried;
+    }
+  };
 
   // v1 called these "screens" and this reads them unchanged, on purpose: nobody should have
   // to write their steps twice to get a second kind of check out of them.
   for (const screen of [...(config.screens ?? []), ...(config.journeys ?? [])]) {
     if (!screen || typeof screen !== 'object') continue;
-    const name = String(screen.name ?? screen.url ?? 'a screen');
+    const wanted = String(screen.name ?? screen.url ?? 'a screen');
     /** @type {Record<string, any>[]} */
     const steps = [];
     if (screen.url !== undefined) steps.push({ act: 'open', goto: String(screen.url), note: `open ${screen.url}` });
     for (const step of screen.steps ?? []) steps.push({ act: actOf(step), ...step });
+
+    // The same name AND the same steps is one screen listed twice — the settings and the
+    // journeys file both naming it, most often — and folding those together loses nothing.
+    // A different set of steps under the same name is a different screen.
+    const shape = JSON.stringify(steps);
+    if (shapes.get(wanted) === shape) continue;
+    const name = freeName(wanted);
+    shapes.set(name, shape);
     journeys.set(name, {
       name,
-      describe: String(screen.describe ?? screen.why ?? `walk ${name}`),
+      describe: String(
+        screen.describe ??
+        screen.why ??
+        (name === wanted
+          ? `walk ${name}`
+          : `walk ${name} — the settings name two different screens "${wanted}", so this is the second of them`)
+      ),
       source: 'code',
       surface: 'web',
       from: 'the project settings',
@@ -205,8 +290,7 @@ export function journeysFrom(input) {
       if (sample === undefined) unfilled.push(need);
       else url = url.replace(new RegExp(`\\[\\.{0,3}${need}\\]|:${need}`), encodeURIComponent(String(sample)));
     }
-    const name = `page ${page.url}`;
-    if (journeys.has(name)) continue;
+    const name = freeName(`page ${page.url}`);
     journeys.set(name, {
       name,
       describe: `open ${page.url} and read what the screen says`,
@@ -230,6 +314,28 @@ export function journeysFrom(input) {
     });
   }
 
+  // Last, and after the front-page fallback so a project made entirely of holes still gets
+  // one real journey. A folder nobody could open is a journey that says out loud it was not
+  // walked: the engine turns a journey carrying `skip` into missing coverage, which is the
+  // only route from here to the ledger. Without it, a page behind that folder was never
+  // listed, so nothing anywhere in the run would ever have mentioned it — and a page nobody
+  // listed reads exactly like a page that is fine.
+  for (const hole of input.unreadable ?? []) {
+    const name = freeName(`the pages under ${hole.folder}`);
+    journeys.set(name, {
+      name,
+      describe: `the pages under ${hole.folder}`,
+      source: 'code',
+      surface: 'web',
+      from: hole.folder,
+      channels: [],
+      steps: /** @type {any} */ ([]),
+      skip:
+        `"${hole.folder}" could not be opened while looking for this project's pages — ${hole.why} — so nothing under it was listed. ` +
+        'Any page in there was not walked and is not in the count of pages that were. This is a hole, not a pass.',
+    });
+  }
+
   return [...journeys.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 
@@ -290,7 +396,16 @@ export const webAdapter = defineAdapter({
     const framework = ['next', 'react', 'vue', 'svelte', 'astro', '@remix-run/react', 'nuxt', 'solid-js', 'preact', 'vite']
       .find((name) => name in dependencies);
 
-    const pages = await readPageRoutes(project.root);
+    /** @type {{unreadable: {folder: string, why: string}[]}} */
+    const collect = { unreadable: [] };
+    const pages = await readPageRoutes(project.root, collect);
+    if (collect.unreadable.length > 0) {
+      missing.push({
+        what: `permission to read ${collect.unreadable.length === 1 ? 'a folder' : `${collect.unreadable.length} folders`} this project's pages live in: ${collect.unreadable.map((u) => `${u.folder} (${u.why})`).join(', ')}`,
+        unlocks: 'listing the pages under them at all. Nothing under a folder that will not open is walked, counted, or missed, so the run is quiet about that part of the site',
+        howToGet: `Give this account permission to read ${collect.unreadable.length === 1 ? 'it' : 'them'} — on a Mac or Linux that is: chmod +rx ${collect.unreadable[0].folder}`,
+      });
+    }
     const address = config.url ?? config.baseUrl ?? null;
 
     if (!config.start && !address) {
@@ -338,7 +453,10 @@ export const webAdapter = defineAdapter({
 
   /** @param {import('./contract.js').AdapterProject} project */
   async journeys(project) {
-    return journeysFrom({ config: project.config ?? {}, pages: await readPageRoutes(project.root) });
+    /** @type {{unreadable: {folder: string, why: string}[]}} */
+    const collect = { unreadable: [] };
+    const pages = await readPageRoutes(project.root, collect);
+    return journeysFrom({ config: project.config ?? {}, pages, unreadable: collect.unreadable });
   },
 
   /**
@@ -419,7 +537,7 @@ export const webAdapter = defineAdapter({
       if (!verdict.safe) notes.push(verdict.why);
       else {
         const done = await new Promise((resolve) => {
-          const child = spawn(String(config.restore), { shell: true, cwd: work, env, stdio: 'ignore' });
+          const child = spawnServer(String(config.restore), { cwd: work, env, stdio: 'ignore' });
           child.on('error', () => resolve(false));
           child.on('close', (code) => resolve(code === 0));
         });
@@ -431,7 +549,7 @@ export const webAdapter = defineAdapter({
     const said = [];
     /** @type {string|null} */
     let exited = null;
-    const child = spawn(String(config.start), { shell: true, cwd: work, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    const child = spawnServer(String(config.start), { cwd: work, env });
     child.stdout?.on('data', (c) => said.push(c));
     child.stderr?.on('data', (c) => said.push(c));
     child.on('close', (code, signal) => {
@@ -440,14 +558,14 @@ export const webAdapter = defineAdapter({
 
     const up = await waitForServer(port, { timeoutMs: config.startTimeoutMs ?? 90000, crashed: () => exited });
     if (!up.up) {
-      child.kill('SIGTERM');
+      await stopServer(child);
       return {
         build,
         root: work,
         ready: false,
         why: `${up.why} What it printed while trying: ${trimForStorage(Buffer.concat(said).toString('utf8'), 1500).text || '(nothing)'}`,
         dispose: async () => {
-          child.kill('SIGKILL');
+          await stopServer(child);
           await fsp.rm(base, { recursive: true, force: true });
         },
       };
@@ -466,9 +584,7 @@ export const webAdapter = defineAdapter({
         running.delete(build.id);
         if (!held) return;
         // Only ever the process we started ourselves.
-        held.child?.kill('SIGTERM');
-        await new Promise((r) => setTimeout(r, 400));
-        if (held.child && held.child.exitCode === null) held.child.kill('SIGKILL');
+        await stopServer(held.child);
         await fsp.rm(base, { recursive: true, force: true });
       },
     };
@@ -525,6 +641,9 @@ export const webAdapter = defineAdapter({
     const viewport = viewportFrom(config);
     const window = await openWindow({
       chromium: held.playwright.chromium,
+      // Which browser was chosen for this machine. Without it a driver that downloads no
+      // browser of its own looks for one that is not there.
+      executable: held.playwright.executable,
       scratchDir: ctx.scratchDir,
       viewport,
       colorScheme: config.colorScheme ?? 'light',
@@ -658,7 +777,7 @@ export const webAdapter = defineAdapter({
   },
 
   async teardown() {
-    for (const [, held] of running) held.child?.kill('SIGTERM');
+    for (const [, held] of running) await stopServer(held.child);
     running.clear();
   },
 });
@@ -1001,9 +1120,21 @@ export function complaintKey(message) {
 }
 
 /**
+ * A name a picture can be saved under.
+ *
+ * Cut with a fingerprint on the end, never cut alone. This is a FILE name: two checkpoints
+ * whose names agreed for eighty characters were saved over each other, so the picture
+ * offered as evidence for one finding was a photograph of a different screen — and nothing
+ * about it looked wrong. Long file names are the normal case here, because the name is the
+ * build, the journey and the checkpoint run together.
+ *
  * @param {string} name
  * @returns {string}
  */
 function fileSafe(name) {
-  return String(name).replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 80) || 'checkpoint';
+  const clean = String(name).replace(/[^A-Za-z0-9._-]+/g, '-');
+  if (clean === '') return 'checkpoint';
+  if (clean.length <= 80) return clean;
+  const mark = crypto.createHash('sha256').update(clean).digest('hex').slice(0, 8);
+  return `${clean.slice(0, 71)}-${mark}`;
 }

package/src/v2/adapters/windows.js

@@ -1201,7 +1201,24 @@ export const windowsAdapter = defineAdapter({
           // Pixels last, and only as evidence. A picture is written to the evidence folder and
           // pointed at; it is never the thing compared.
           const shot = await runner.call('shot', { hwnd: window.hwnd }, { timeoutMs: 45_000 });
-          if (shot.ok && shot.png && Number(shot.bytes) <= MAX_SHOT_BYTES) {
+          // THREE WAYS OUT OF HERE AND TWO OF THEM USED TO BE SILENT. A picture that failed,
+          // came back empty, or came back bigger than the cap simply produced no observation
+          // at all — so the pixels channel dropped out of the run without a word, and the
+          // ledger reported the same coverage as a run where every window was photographed.
+          // A cap is a decision and a decision has to be visible; a failure is a hole and a
+          // hole has to be named. Neither is a reason to lose the rest of the walk.
+          const tooBig = shot.ok === true && Boolean(shot.png) && Number(shot.bytes) > MAX_SHOT_BYTES;
+          if (!shot.ok || !shot.png || tooBig) {
+            seen.push(notCovered({
+              channel: 'pixels',
+              path: joinPath('screen', label, 'picture'),
+              reason: tooBig ? 'too big' : 'crashed',
+              says: tooBig
+                ? `The picture of "${label}" came back at ${sizeBucket(Number(shot.bytes))}, over the ${sizeBucket(MAX_SHOT_BYTES)} this keeps, so it was not stored. Every other channel still looked at that window; only the picture is missing.`
+                : `No picture of "${label}" could be taken${shot.error ? `: ${String(shot.error)}` : '.'} Every other channel still looked at that window; only the picture is missing.`,
+            }));
+          }
+          if (shot.ok && shot.png && !tooBig) {
             const file = path.join(ctx.evidenceDir, `windows-${journey.name}-${label.replace(/[^a-z0-9]+/gi, '-')}.png`);
             await fsp.writeFile(file, Buffer.from(String(shot.png), 'base64'));
             seen.push(observation({