staysfixed 0.9.1 → 0.11.0

package/src/report/html.js

@@ -9,7 +9,7 @@
 
 import fsp from 'node:fs/promises';
 import path from 'node:path';
-import { verdictFor, plainTime, countText } from './console.js';
+import { verdictFor, plainTime, countText, guardVerdict } from './console.js';
 
 /**
  * @param {unknown} s
@@ -210,27 +210,51 @@ function troubleCard(p, actual) {
  */
 function guardsSection(guards) {
   if (guards.length === 0) return '';
-  const failed = guards.filter((g) => g.status === 'failed');
+  // Counted by what each result actually says, not by its status. "3 of 3 bugs that were
+  // fixed are back" was printed on 2026-08-31 over one real failure, one guard whose clock
+  // ran out and one that was never even asked — and "All 3 bugs that were fixed are still
+  // fixed" was printed over three guards marked skip. Both sentences were about guards
+  // nobody had an answer from.
+  const back = guards.filter((g) => guardVerdict(g) === 'back');
+  const held = guards.filter((g) => guardVerdict(g) === 'held');
+  const unanswered = guards.length - back.length - held.length;
   const out = [];
   out.push('<h2>Guards</h2>');
-  out.push(
-    `<p class="lead">${
-      failed.length === 0
-        ? `All ${countText(guards.length)} ${plural(guards.length, 'bug', 'bugs')} that were fixed are still fixed.`
-        : `${countText(failed.length)} of ${countText(guards.length)} bugs that were fixed ${plural(failed.length, 'is', 'are')} back.`
-    }</p>`,
-  );
+  const lead = [];
+  if (back.length > 0) {
+    lead.push(`${countText(back.length)} of ${countText(guards.length)} bugs that were fixed ${plural(back.length, 'is', 'are')} back.`);
+  } else if (held.length === guards.length) {
+    lead.push(`All ${countText(guards.length)} ${plural(guards.length, 'bug', 'bugs')} that were fixed are still fixed.`);
+  } else if (held.length > 0) {
+    lead.push(`${countText(held.length)} of ${countText(guards.length)} bugs that were fixed ${plural(held.length, 'is', 'are')} still fixed.`);
+  } else {
+    lead.push(`Not one of these ${countText(guards.length)} guards gave an answer.`);
+  }
+  if (unanswered > 0) {
+    lead.push(
+      `${countText(unanswered)} ${plural(unanswered, 'guard', 'guards')} ${plural(unanswered, 'was', 'were')} never answered — left out, out of time, or asking nothing at all.`,
+    );
+  }
+  out.push(`<p class="lead">${lead.join(' ')}</p>`);
   out.push('<section class="card guards"><ul class="guardlist">');
   for (const g of guards) {
-    const state = g.status === 'passed' ? 'good' : g.status === 'skipped' ? 'muted' : 'bad';
+    const verdict = guardVerdict(g);
+    const state = verdict === 'held' ? 'good' : verdict === 'back' ? 'bad' : 'muted';
     out.push(`<li class="${state}">`);
     out.push(`<span class="dot"></span><span class="gname">${escapeHtml(g.name)}</span>`);
-    if (g.status === 'failed') {
+    if (verdict === 'left out') {
+      out.push('<div class="note">left out on purpose</div>');
+    } else if (verdict !== 'held') {
       if (g.failedAt) out.push(`<div class="claim">expected: ${escapeHtml(g.failedAt)}</div>`);
       if (g.message && g.message !== g.failedAt) out.push(`<div class="claim">${escapeHtml(g.message)}</div>`);
-      if (g.because) out.push(`<div class="because">Why this guard exists: ${escapeHtml(g.because)}</div>`);
-    } else if (g.status === 'skipped') {
-      out.push('<div class="note">left out on purpose</div>');
+      // The story is what says whether a failure matters, so it belongs under a returned bug.
+      // Under a guard that ran out of time it reads as that bug being back, which is exactly
+      // what nobody knows. An empty guard gets it in the words that fit an empty guard.
+      if (g.because && verdict === 'back') {
+        out.push(`<div class="because">Why this guard exists: ${escapeHtml(g.because)}</div>`);
+      } else if (g.because && /** @type {any} */ (g).assertedNothing === true) {
+        out.push(`<div class="because">What it was meant to protect: ${escapeHtml(g.because)}</div>`);
+      }
     }
     out.push('</li>');
   }
@@ -260,10 +284,30 @@ function condemnedSection(names) {
  */
 function passedSection(passed) {
   if (passed.length === 0) return '';
-  const items = passed.map((p) => `<li><code>${escapeHtml(p.name)}</code></li>`).join('');
+  // "Exactly as approved" has to mean exactly, or it is the most expensive sentence on this
+  // page. A picture that differs and is waved through by `tolerance.pixels` was listed here in
+  // the same words as one that matched byte for byte — which is how a missing letter in a
+  // heading, 593 plainly visible pixels, sat under "still looks exactly as approved" while an
+  // allowance of 2,592 quietly absorbed it. The terminal was taught to say this in full and
+  // the report was not, so the same run said two different things depending where you read it.
+  const allowed = passed.filter((p) => (p.diffPixels ?? 0) > 0);
+  const items = passed
+    .map((p) => {
+      const moved = p.diffPixels ?? 0;
+      const note =
+        moved > 0
+          ? ` <span class="muted">the same, apart from ${countText(moved)} ${plural(moved, 'pixel', 'pixels')} your tolerance allowed</span>`
+          : '';
+      return `<li><code>${escapeHtml(p.name)}</code>${note}</li>`;
+    })
+    .join('');
+  const summary =
+    allowed.length === 0
+      ? `${countText(passed.length)} ${plural(passed.length, 'screen', 'screens')} still ${plural(passed.length, 'looks', 'look')} exactly as approved`
+      : `${countText(passed.length)} ${plural(passed.length, 'screen', 'screens')} passed — ${countText(allowed.length)} of ${plural(allowed.length, 'them', 'them')} only because your tolerance allowed what changed`;
   return [
     '<details class="card quiet">',
-    `<summary>${countText(passed.length)} ${plural(passed.length, 'screen', 'screens')} still ${plural(passed.length, 'looks', 'look')} exactly as approved</summary>`,
+    `<summary>${summary}</summary>`,
     `<ul class="plain columns">${items}</ul>`,
     '</details>',
   ].join('\n');
@@ -298,13 +342,25 @@ async function buildHtml(project, run) {
   if (run.platform) meta.push(`on ${escapeHtml(run.platform)}`);
   body.push(`<p class="meta">${meta.join(' &middot; ')}</p>`);
   const chips = [];
-  if (passed.length) chips.push(`<span class="chip good">${countText(passed.length)} unchanged</span>`);
+  // Not "unchanged" when a tolerance allowed the change through. Same sentence, same reason.
+  if (passed.length) {
+    const untouched = passed.filter((p) => (p.diffPixels ?? 0) === 0).length;
+    chips.push(
+      `<span class="chip good">${countText(passed.length)} ${untouched === passed.length ? 'unchanged' : 'passed'}</span>`,
+    );
+  }
   if (changed.length) chips.push(`<span class="chip bad">${countText(changed.length)} changed</span>`);
   if (fresh.length) chips.push(`<span class="chip warn">${countText(fresh.length)} new</span>`);
   if (trouble.length) chips.push(`<span class="chip bad">${countText(trouble.length)} could not be checked</span>`);
   if (guards.length) {
-    const bad = guards.filter((g) => g.status === 'failed').length;
-    chips.push(`<span class="chip ${bad ? 'bad' : 'good'}">${countText(guards.length)} ${plural(guards.length, 'guard', 'guards')}${bad ? `, ${countText(bad)} failed` : ' holding'}</span>`);
+    // "1 failed" over a guard that only ran out of time is the headline bug of this report in
+    // miniature. Counted the same way every other sentence about guards is counted now.
+    const bad = guards.filter((g) => guardVerdict(g) === 'back').length;
+    const unheard = guards.filter((g) => guardVerdict(g) === 'unanswered').length;
+    const note = bad ? `, ${countText(bad)} failed` : unheard ? `, ${countText(unheard)} unanswered` : ' holding';
+    chips.push(
+      `<span class="chip ${bad ? 'bad' : unheard ? 'warn' : 'good'}">${countText(guards.length)} ${plural(guards.length, 'guard', 'guards')}${note}</span>`,
+    );
   }
   if (chips.length) body.push(`<p class="chips">${chips.join('')}</p>`);
   body.push('</header>');

package/src/types.js

@@ -501,6 +501,11 @@ export {};
  * @property {string} [message]
  * @property {string} [failedAt]              The plain-language expectation that failed.
  * @property {string} [because]               Why a guard exists.
+ * @property {boolean} [timedOut]             A guard whose clock ran out. It is reported with the status
+ *                                          'failed' because a question nobody answered must never count
+ *                                          as a pass — but it is not a bug coming back, and anything
+ *                                          drawing this stream has to be able to tell the two apart.
+ * @property {boolean} [assertedNothing]      A guard that finished without asking a single question.
  * @property {string} [thumbnail]             A small JPEG as a data: URI — an instant preview, shown
  *                                          while the real file is still being written.
  * @property {string} [shotFile]              file:// URL of the FULL-RESOLUTION picture just taken.

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

@@ -40,6 +40,11 @@ import http from 'node:http';
 import net from 'node:net';
 import { execFile, spawn } from 'node:child_process';
 
+// Every wait in this file has a limit and every limit says what it was waiting for. The pieces
+// that do that live in process.js, next to the one function in this codebase whose whole job is
+// running a program and waiting for it.
+import { boundedMs, endOfChild, letGoOf } from './process.js';
+
 // ---------------------------------------------------------------------------
 // Finding the tools
 // ---------------------------------------------------------------------------
@@ -190,7 +195,11 @@ export function run(file, args, opts = {}) {
       file,
       args,
       {
-        timeout: opts.timeoutMs ?? 120000,
+        // `boundedMs` and not the number as handed over. `execFile` only arms its timeout when
+        // the value is greater than zero, so a limit of NaN — which is what a limit read out of
+        // a settings file as text becomes — switches the limit OFF rather than shortening it,
+        // and adb hanging on a wedged device then hangs the whole check with no output at all.
+        timeout: boundedMs(opts.timeoutMs, 120000),
         signal: opts.signal,
         cwd: opts.cwd,
         maxBuffer: opts.maxBuffer ?? 32 * 1024 * 1024,
@@ -259,18 +268,41 @@ export class Device {
 
   /**
    * Run something and get raw bytes back — a screenshot, a file.
+   *
+   * This had neither a limit nor a size cap, and it settled on `close`. All three were the same
+   * bug: `close` does not mean the program ended, it means nobody anywhere is holding its pipes
+   * any more, and `adb` keeps a server daemon of its own that inherits them. So a device that
+   * stopped answering held this open for ever, with no output and nothing to act on — measured
+   * as a shape on 2026-08-31 against a fake program that leaves an orphan behind. It now ends,
+   * says why, and hands back what it did get.
+   *
    * @param {string} command
+   * @param {{timeoutMs?: number, mostBytes?: number}} [opts]
    * @returns {Promise<Buffer>}
    */
-  bytes(command) {
-    return new Promise((resolve, reject) => {
-      const child = spawn(this.adb, ['-s', this.serial, 'exec-out', command], { signal: this.signal });
-      /** @type {Buffer[]} */
-      const chunks = [];
-      child.stdout.on('data', (b) => chunks.push(b));
-      child.on('error', reject);
-      child.on('close', () => resolve(Buffer.concat(chunks)));
+  async bytes(command, opts = {}) {
+    const mostBytes = Math.max(1, Number(opts.mostBytes) || 64 * 1024 * 1024);
+    const child = spawn(this.adb, ['-s', this.serial, 'exec-out', command], { signal: this.signal });
+    /** @type {Buffer[]} */
+    const chunks = [];
+    let held = 0;
+    let tooMuch = false;
+    child.stdout.on('data', (/** @type {Buffer} */ b) => {
+      // Kept reading even once it is too much, because a reader that stops reading is a pipe
+      // that fills up, and a full pipe blocks the writer for ever — which is the same hang
+      // wearing a different hat.
+      if (held >= mostBytes) { tooMuch = true; return; }
+      held += b.length;
+      chunks.push(b);
     });
+    child.stderr?.resume();
+    const ended = await endOfChild(child, {
+      limitMs: boundedMs(opts.timeoutMs, 60000),
+      what: `the device to finish "${command.slice(0, 60)}"`,
+    });
+    if (ended.gaveUp) throw new Error(ended.why);
+    if (tooMuch) throw new Error(`"${command.slice(0, 60)}" sent back more than ${Math.round(mostBytes / (1024 * 1024))}MB, which is more than anything this asks for should ever be. It was stopped rather than held in memory.`);
+    return Buffer.concat(chunks);
   }
 
   /**
@@ -1566,13 +1598,25 @@ export async function pidOf(device, pkg) {
 
 /**
  * Take a picture. Evidence only — never the accusation.
+ *
+ * A device that will not hand one over is a hole in the evidence and nothing more, so it is
+ * caught here and said in a sentence. Letting it throw would end the whole walk over a
+ * screenshot, and the six channels that had already read the app properly would be thrown away
+ * with it.
+ *
  * @param {Device} device
  * @param {string} to
- * @returns {Promise<{ok: boolean, bytes: number, path: string}>}
+ * @returns {Promise<{ok: boolean, bytes: number, path: string, why?: string}>}
  */
 export async function screenshot(device, to) {
-  const png = await device.bytes('screencap -p');
-  if (png.length < 8 || png[0] !== 0x89) return { ok: false, bytes: png.length, path: to };
+  /** @type {Buffer} */
+  let png;
+  try {
+    png = await device.bytes('screencap -p');
+  } catch (e) {
+    return { ok: false, bytes: 0, path: to, why: e instanceof Error ? e.message : String(e) };
+  }
+  if (png.length < 8 || png[0] !== 0x89) return { ok: false, bytes: png.length, path: to, why: 'the device sent back something that is not a picture' };
   await fsp.mkdir(path.dirname(to), { recursive: true });
   await fsp.writeFile(to, png);
   return { ok: true, bytes: png.length, path: to };
@@ -1701,6 +1745,12 @@ export async function startEmulator(spec) {
       // Falling through to the process is fine; the console may already be gone.
     }
     if (!child.killed) child.kill('SIGTERM');
+    // And let go of its pipes rather than trusting them to close. An emulator is a family of
+    // processes and the helpers inherit the writing end of these; a survivor holding one keeps
+    // Node's event loop awake, so the check finishes its work, prints its verdict and then
+    // never returns. Measured in that exact shape on 2026-08-31 for the desktop adapter, and
+    // the emulator has the same shape.
+    letGoOf(child);
   };
 
   if (!ready.ready) {

package/src/v2/adapters/contract.js

@@ -400,9 +400,19 @@ export function observation(spec) {
   if (spec.surface) meta.surface = spec.surface;
   if (spec.covered === false) {
     // The engine reads `refused` when it builds the coverage ledger. Everything an adapter
-    // could not look at lands here, whichever of the reasons it was — a payment it would not
-    // make, a runtime this machine does not have, a parameter nobody supplied. They are all
-    // the same thing to a reader: a hole, with the reason attached, and never a pass.
+    // could not look at IN FULL lands here, whichever of the reasons it was — a payment it
+    // would not make, a runtime this machine does not have, a parameter nobody supplied.
+    // They are all the same thing to the ledger: a hole, with the reason attached, and never
+    // a pass.
+    //
+    // IT DOES NOT MEAN "NOTHING ANSWERED", and reading it that way is wrong in one specific
+    // case that really happens: `too big` sets it on a REAL value that was only partly kept.
+    // A large log is a genuine observation of the product and has to go on being compared;
+    // treating it as a refusal would drop a real address out of the comparison and, worse,
+    // could block a healthy release. So anything deciding whether an address ANSWERED reads
+    // the value — see `src/v2/refusal.js`, which is the one place that question is answered
+    // — and never this flag. Written down on 2026-08-31 after the refusal lane found the two
+    // meanings sharing one field.
     meta.refused = true;
     meta.refusedWhy = `${NOT_COVERED_MEANING[spec.reason ?? 'refused']} (${spec.reason ?? 'refused'})`;
   }
@@ -512,7 +522,11 @@ export function howLongItTook(spec) {
     // never become a difference. The measurement lives in the sentence, which is never compared.
     value: `not compared — ${NOT_COVERED_MEANING['measures the machine']}`,
     says:
-      `${spec.what} took ${timeBucket(spec.ms)}. That is recorded and NOT compared: a stopwatch on a shared machine ` +
+      // "took" reads wrong in front of two of the rungs — "took quick", "took instant" —
+      // and this sentence goes in front of a person. The rungs are values, kept as they are
+      // because they are recorded; the sentence bends around them instead. Measured on a
+      // real run 2026-08-31, which printed "Walking the steps of "home" took quick."
+      `${spec.what}: ${timeBucket(spec.ms)}. That is recorded and NOT compared: a stopwatch on a shared machine ` +
       `measures the machine as much as the product, so a busy laptop would otherwise invent a slowdown that nobody caused. ` +
       `A build that hangs is still caught — it gets stopped for taking too long, and how it finished is compared.` +
       (spec.andAlso ? ` ${spec.andAlso}` : ''),

package/src/v2/adapters/electron.js

@@ -54,7 +54,7 @@ import {
   countBucket, defineAdapter, howLongItTook, joinPath, notCovered, observation, sizeBucket,
   timeBucket, trimForStorage, undoOurFootprint,
 } from './contract.js';
-import { compareTrees, snapshotTree } from './process.js';
+import { boundedCount, boundedMs, compareTrees, snapshotTree, withLimit } from './process.js';
 import {
   describeIsolation, releaseEverything, releaseIsolation, reserveIsolation, startIsolated,
   verifyAlone,
@@ -377,11 +377,17 @@ async function askFor(url) {
  * @param {object} opts
  * @param {number} opts.timeoutMs
  * @param {() => string|null} opts.died   A sentence when the app has already quit, else null.
+ * @param {AbortSignal} [opts.signal]
  * @returns {Promise<{webSocketDebuggerUrl: string, title: string}>}
  */
 async function waitForMainProcess(port, opts) {
-  const until = Date.now() + opts.timeoutMs;
+  // `boundedMs` and not the number as given, because this limit comes from a project's own
+  // settings file. A limit of NaN — which is what `startTimeoutMs: "60s"` becomes — makes
+  // `Date.now() > until` false for ever, and this loop would then poll a dead port until
+  // somebody killed the tool, with no output and no explanation.
+  const until = Date.now() + boundedMs(opts.timeoutMs, 60_000);
   for (;;) {
+    if (opts.signal?.aborted) throw new Error('The run was stopped while waiting for the app to open its main-process debugging connection.');
     const gone = opts.died();
     if (gone) throw new Error(gone);
     try {
@@ -406,13 +412,17 @@ async function waitForMainProcess(port, opts) {
  * @param {object} opts
  * @param {number} opts.timeoutMs
  * @param {() => string|null} opts.died
+ * @param {AbortSignal} [opts.signal]
  * @returns {Promise<{id: string, title: string, url: string}>}
  */
 async function waitForWindow(port, match, opts) {
-  const until = Date.now() + opts.timeoutMs;
+  // Guarded for the same reason as the wait above it: a limit that is not a number turns this
+  // endless-looking loop into a genuinely endless one.
+  const until = Date.now() + boundedMs(opts.timeoutMs, 60_000);
   /** @type {any[]} */
   let pages = [];
   for (;;) {
+    if (opts.signal?.aborted) throw new Error('The run was stopped while waiting for the app to open a window.');
     const gone = opts.died();
     if (gone) throw new Error(gone);
     try {
@@ -465,10 +475,35 @@ async function waitForWindow(port, match, opts) {
  * @returns {Promise<OpenApp>}
  */
 export async function openApp(opts) {
-  const timeoutMs = opts.timeoutMs ?? 60_000;
+  // The whole open, on ONE clock, on top of the clock each individual step already has.
+  //
+  // Every step below is bounded on its own, and that was still not enough: a run that gives up
+  // on eight things in a row for sixty seconds each has waited eight minutes, and the recorded
+  // symptom this file is being fixed for — an Electron check on 2026-08-30 that produced no
+  // output at all and never came back — is indistinguishable from a very long wait. So there
+  // is an outer limit as well, and because a bare "it timed out" sends somebody looking in
+  // every wrong place first, it names the step it was actually stuck in.
+  const timeoutMs = boundedMs(opts.timeoutMs, 60_000);
+  const stage = { at: 'the app to be started' };
+  return withLimit(openTheApp(opts, timeoutMs, stage), {
+    limitMs: timeoutMs * 3,
+    what: () => `${stage.at}. Nothing about this build was checked.`,
+  });
+}
+
+/**
+ * The steps of opening one app. Wrapped by `openApp`, which owns the outer limit.
+ *
+ * @param {Parameters<typeof openApp>[0]} opts
+ * @param {number} timeoutMs
+ * @param {{at: string}} stage   Updated as it goes, so a give-up can name where it stopped.
+ * @returns {Promise<OpenApp>}
+ */
+async function openTheApp(opts, timeoutMs, stage) {
   const isolation = opts.isolation;
   const startedAt = Date.now();
 
+  stage.at = 'the previous copy of this app to be proved gone';
   const alone = await verifyAlone(isolation);
   if (!alone.alone) throw new Error(`${alone.why} Nothing was started, because two copies of one app fight over the same lock and the same settings.`);
 
@@ -480,7 +515,9 @@ export async function openApp(opts) {
   };
 
   // ---- the main process, paused at its first statement
-  const mainTarget = await waitForMainProcess(isolation.inspectPort, { timeoutMs, died });
+  stage.at = `the app to open its main-process debugging connection on port ${isolation.inspectPort}`;
+  const mainTarget = await waitForMainProcess(isolation.inspectPort, { timeoutMs, died, signal: opts.signal });
+  stage.at = 'the app to finish accepting a debugging connection to its main process';
   const main = await connect(mainTarget.webSocketDebuggerUrl, { timeoutMs: 20_000 });
   isolation.closeFirst(() => main.close());
 
@@ -499,6 +536,7 @@ export async function openApp(opts) {
     complain(`the app printed an error: ${text}`.split('\n')[0]);
   });
 
+  stage.at = 'the app to answer the first question about its main process';
   await main.send('Runtime.enable');
   await main.send('Debugger.enable');
 
@@ -507,13 +545,17 @@ export async function openApp(opts) {
   const stopListening = main.on('Debugger.paused', (params) => {
     if (frameId === null) frameId = String(params?.callFrames?.[0]?.callFrameId ?? '') || null;
   });
+  stage.at = 'the app to stop at its first line so the safety boundary can be put in place';
   await main.send('Runtime.runIfWaitingForDebugger');
+  // Five seconds, and it gives up rather than waits: an app that never stops at its first line
+  // is still worth checking, just with a hole in the report where the boundary would have been.
   for (let i = 0; i < 100 && frameId === null; i += 1) await rest(50);
 
   let watching = '';
   /** @type {string[]} */
   let couldNotWatch = [];
   if (frameId) {
+    stage.at = 'the safety boundary to be put in place inside the app';
     const result = await main.send('Debugger.evaluateOnCallFrame', {
       callFrameId: frameId,
       expression: mainProbeScript(),
@@ -531,8 +573,13 @@ export async function openApp(opts) {
   opts.log?.(watching ? `Watching ${watching}.` : 'Nothing is watching the main process from the inside.');
 
   // ---- the window
-  const window = await waitForWindow(isolation.debugPort, opts.windowMatch, { timeoutMs, died });
+  stage.at = opts.windowMatch
+    ? `the app to open a window matching "${opts.windowMatch}"`
+    : 'the app to open a window to look at';
+  const window = await waitForWindow(isolation.debugPort, opts.windowMatch, { timeoutMs, died, signal: opts.signal });
+  stage.at = 'the app to say which window connection to use';
   const version = await askFor(`http://127.0.0.1:${isolation.debugPort}/json/version`);
+  stage.at = 'the app to accept a debugging connection to its window';
   const browser = await connect(String(version.webSocketDebuggerUrl), { timeoutMs: 20_000 });
   isolation.closeFirst(() => browser.close());
   const attached = await browser.send('Target.attachToTarget', { targetId: window.id, flatten: true });
@@ -578,6 +625,7 @@ export async function openApp(opts) {
       browser.send('Fetch.continueRequest', { requestId: params.requestId }, sessionId).catch(() => {});
     });
   });
+  stage.at = "the window to accept the boundary in front of its own network requests";
   await browser.send('Fetch.enable', { patterns: [{ urlPattern: '*' }] }, sessionId).catch(() => {
     couldNotWatch.push("the window's own network requests");
   });
@@ -775,8 +823,12 @@ export function readMeaning(nodes, tidy = (t) => t) {
  * @returns {Promise<{nodes: any[], settled: boolean, reads: number}>}
  */
 export async function settleTree(read, opts = {}) {
-  const tries = opts.tries ?? 8;
-  const gapMs = opts.gapMs ?? 350;
+  // Both of these are settable from a project's own settings file, so both are guarded. A
+  // gap of NaN is a `setTimeout` of one millisecond, which turns "read until it stops moving"
+  // into a spin; a count that is not a number stops the loop running at all and silently
+  // reports an empty screen. Neither says anything out loud, which is why they are pinned.
+  const tries = boundedCount(opts.tries, 8, 200);
+  const gapMs = boundedMs(opts.gapMs, 350, 60_000);
   let previous = '';
   /** @type {any[]} */
   let nodes = [];
@@ -824,16 +876,26 @@ export async function takeStep(app, step) {
 
   if (act === 'wait') {
     if (step.control) {
-      const until = Date.now() + Number(step.timeoutMs ?? 10_000);
+      // `boundedMs` and not `Number(...)`, and this is the one loop in this file that could
+      // genuinely run for ever. A journey is written by hand, and `timeoutMs: "10s"` is
+      // `Number("10s")`, which is NaN — at which point `Date.now() + NaN` is NaN, `Date.now()
+      // > NaN` is false every single time round, and this loop asks the app for its whole
+      // accessibility tree five times a second until somebody kills the tool. No output, no
+      // reason, and it looks exactly like the app hanging rather than the journey being
+      // mistyped. Capped at five minutes as well: a step that waits longer than that for a
+      // control to appear is a mistake in the journey, not patience.
+      const limitMs = boundedMs(step.timeoutMs, 10_000, 5 * 60_000);
+      const until = Date.now() + limitMs;
       for (;;) {
         const tree = await app.browser.send('Accessibility.getFullAXTree', {}, app.sessionId).catch(() => ({ nodes: [] }));
         if (readMeaning(tree.nodes ?? []).some((row) => row.name === String(step.control))) return say(`waited until "${step.control}" appeared`);
-        if (Date.now() > until) return say(`waited for "${step.control}", and it never appeared`, false);
+        if (Date.now() > until) return say(`waited ${timeBucket(limitMs)} for "${step.control}" to appear, and it never did`, false);
         await rest(200);
       }
     }
-    await rest(Number(step.ms ?? 500));
-    return say(`waited ${timeBucket(Number(step.ms ?? 500))}`);
+    const restMs = boundedMs(step.ms, 500, 5 * 60_000);
+    await rest(restMs);
+    return say(`waited ${timeBucket(restMs)}`);
   }
 
   if (act === 'click' || act === 'focus') {
@@ -924,7 +986,21 @@ export async function exerciseChannel(app, channel, args) {
     if (thrown) return { answered: false, why: 'it threw: ' + String(thrown && thrown.message || thrown) };
     return { answered: true, value: reply === undefined ? null : reply, why: 'it answered' };
   })()`;
-  const result = await app.main.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true });
+  // On a clock of its own, and it says which door it was knocking on. This is the only place
+  // in this adapter that makes the app RUN something, so it is the only place where the app's
+  // own code can decide never to answer — a handler that awaits a promise nobody resolves
+  // holds this open, and without a name in the sentence the report would say "the app did not
+  // answer" about an app with four hundred doors.
+  /** @type {any} */
+  let result;
+  try {
+    result = await withLimit(
+      app.main.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }),
+      { limitMs: 30_000, what: `the private channel "${channel}" to answer` },
+    );
+  } catch (e) {
+    return { answered: false, value: null, why: e instanceof Error ? e.message : String(e) };
+  }
   if (result?.exceptionDetails) {
     return { answered: false, value: null, why: `asking it threw: ${String(result.exceptionDetails.text ?? '')}` };
   }
@@ -1563,7 +1639,13 @@ export const electronAdapter = defineAdapter({
         return tree?.nodes ?? [];
       }, { tries: config.settleTries ?? 8, gapMs: config.settleGapMs ?? 350 });
 
-      const read = await app.main.send('Runtime.evaluate', { expression: mainReadScript(), returnByValue: true, awaitPromise: true });
+      // Bounded, and it degrades rather than throws. Everything the window said has already
+      // been collected by this point, and losing all of it because the main process went quiet
+      // would turn one hole into a whole unchecked build.
+      const read = await withLimit(
+        app.main.send('Runtime.evaluate', { expression: mainReadScript(), returnByValue: true, awaitPromise: true }),
+        { limitMs: 30_000, what: 'the main process to say what it is, what doors it has open and what it did' },
+      ).catch((e) => ({ result: { value: { problems: [e instanceof Error ? e.message : String(e)] } } }));
       const reading = read?.result?.value ?? { problems: ['the main process would not say anything about itself'] };
       if (Array.isArray(app.couldNotWatch) && app.couldNotWatch.length > 0) {
         reading.effects = reading.effects ?? {};