kryptheon 0.1.8 → 0.1.10

package/bin/kryptheon.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // The kryptheon CLI. A thin wrapper so nobody has to remember Playwright's
 // command line or edit a config file. Everything here shells out to the
 // Playwright binary that ships with this package.
@@ -14,6 +14,9 @@ const { spawn, spawnSync } = require('child_process');
 const os = require('os');
 const secrets = require(require('path').join(__dirname, '..', 'kryptheon-secrets.js'));
 const replay = require('../kryptheon-replay.js');
+const selectors = require('../kryptheon-selectors.js');
+const recordings = require('../kryptheon-recordings.js');
+const cleanup = require('../kryptheon-cleanup.js');
 
 const PACKAGE_DIR = path.join(__dirname, '..');
 const USER_DIR = process.cwd();
@@ -23,8 +26,22 @@ const TESTS_DIR = path.join(USER_DIR, 'tests');
 const MIN_NODE = [20, 6, 0];
 
 // How long to wait for a browser window to appear before giving up.
-const WINDOW_POLL_MS = 3000;
+//
+// The budget is spent only on time we could actually see. A probe that does
+// not answer tells us nothing about the browser, so it must not count against
+// the person running the command - and the hard limit is there so that a probe
+// which never answers still ends the wait rather than hanging forever.
+//
+// Measured on a warm machine, launch to a detectable window is about 2.5s, so
+// 30s is generous; the number that used to matter more was how the waiting was
+// counted, which was by ticks rather than by the clock.
+const WINDOW_POLL_MS = 5000;
 const WINDOW_TIMEOUT_MS = 30000;
+const WINDOW_HARD_LIMIT_MS = 90000;
+// Lower than the poll interval on purpose: a probe still running when the next
+// one is due is of no use, and every extra second it holds the loop is a second
+// the watchdog is blind.
+const WINDOW_PROBE_TIMEOUT_MS = 4000;
 
 function nodeIsTooOld(version) {
   const parts = String(version || process.versions.node).split('.').map(Number);
@@ -52,6 +69,7 @@ function usage() {
   console.log('  kryptheon record <url>   open your app and record what you do as a test');
   console.log('  kryptheon check          run every recorded test and report in plain language');
   console.log('  kryptheon accept <name>  agree that one test\'s new result is the correct one');
+  console.log('  kryptheon remove [name]  list the recordings, or remove one you no longer want');
   console.log('  kryptheon setup-ai       tell your AI assistant to check its work');
   console.log('');
   console.log('  add --quiet to check for one line when everything passes');
@@ -276,6 +294,38 @@ function explainUnreachable(url, kind) {
 
 // Codegen writes Node/Playwright traces to stderr. We never show those; we
 // pick out the part that means something and say it in plain words.
+/**
+ * The lines codegen wrote that look like a real complaint, shown verbatim.
+ *
+ * Playwright's stderr also carries banners and progress noise, so only lines
+ * that read as an error are lifted out - a wall of unrelated output would be
+ * worse than none. Nothing is invented here: if it said nothing, nothing is
+ * printed and the usual explanation follows.
+ */
+function codegenComplaints(stderr, limit) {
+  const seen = Object.create(null);
+  const out = [];
+  for (const raw of String(stderr || '').split('\n')) {
+    const line = raw.replace(/\s+/g, ' ').trim();
+    if (!line) continue;
+    if (!/(^|\b)(Error|error:|ERR_|EACCES|EPERM|ENOENT|Failed|failed to|Timeout|not found)/.test(line)) continue;
+    if (seen[line]) continue;
+    seen[line] = true;
+    out.push(line.length > 160 ? line.slice(0, 157) + '...' : line);
+    if (out.length >= (limit || 3)) break;
+  }
+  return out;
+}
+
+function reportCodegenSaid(stderr) {
+  const said = codegenComplaints(stderr);
+  if (!said.length) return false;
+  console.error('');
+  console.error('  The browser reported:');
+  for (const line of said) console.error('    ' + line);
+  return true;
+}
+
 function explainCodegenFailure(url, stderr) {
   const text = String(stderr || '');
   if (/ERR_CONNECTION_REFUSED/.test(text)) return explainUnreachable(url, 'refused');
@@ -539,8 +589,149 @@ function explainNoWindow() {
   }
 }
 
-// Is a Playwright-controlled browser actually showing a window?
-function browserWindowIsUp() {
+// The browser is there and running; only the window could not be seen. Telling
+// this person their browser never opened would be plainly wrong, so the way
+// past the check comes first rather than buried at the bottom of a list.
+function windowUndetectedLines(seconds) {
+  return [
+    '',
+    '  The browser is running, but no window could be seen.',
+    '',
+    '  A browser process started and was still going after ' + seconds + ' seconds,',
+    '  so this is most likely the check being wrong rather than the browser.',
+    '',
+    '  If the window is open in front of you, run it again with the check off:',
+    '    KRYPTHEON_FORCE_RECORD=1 kryptheon record <url>',
+    '',
+    '  If there is no window on screen, the browser may have opened somewhere',
+    '  with no desktop to draw on - a remote session, a container, or an AI',
+    '  assistant running the command for you.',
+    '',
+    '  Nothing was recorded.',
+    '',
+  ];
+}
+
+// The probe kept failing to answer. Nothing was learned about the browser
+// either way, and saying "no window appeared" would be inventing a fact.
+function probeUnclearLines(answered, unanswered) {
+  return [
+    '',
+    '  Could not tell whether a browser window opened.',
+    '',
+    '  The check that looks for the window did not answer ' + unanswered + ' of its',
+    '  ' + (answered + unanswered) + ' attempts, so there is nothing to go on. This is usually a',
+    '  machine under load, or security software holding up the check itself.',
+    '',
+    '  If the window is open in front of you, run it again with the check off:',
+    '    KRYPTHEON_FORCE_RECORD=1 kryptheon record <url>',
+    '',
+    '  Otherwise just run the same command again.',
+    '',
+    '  Nothing was recorded.',
+    '',
+  ];
+}
+
+/**
+ * Decides, tick by tick, whether to keep waiting for the browser window.
+ *
+ * Kept apart from the timer and the process so it can be driven directly: the
+ * cases worth checking are a probe that answers slowly, one that never answers,
+ * and a browser that runs without a window, none of which are reachable by
+ * launching a real browser and hoping.
+ *
+ * Returns null to keep waiting, or a verdict:
+ *   'window'        - a window is up, stop watching
+ *   'no-window'     - the browser ran for the whole budget without one
+ *   'never-started' - no browser process ever appeared
+ *   'unclear'       - the probe mostly did not answer, so nothing is known
+ */
+function createWindowWatch(options) {
+  const opts = options || {};
+  const probe = opts.probe || inspectBrowserWindows;
+  const clock = opts.now || Date.now;
+  const budgetMs = opts.budgetMs == null ? WINDOW_TIMEOUT_MS : opts.budgetMs;
+  const hardLimitMs = opts.hardLimitMs == null ? WINDOW_HARD_LIMIT_MS : opts.hardLimitMs;
+
+  const started = clock();
+  let lastTick = started;
+  // Time we could actually see, in milliseconds. Counted from the clock rather
+  // than by adding the poll interval per tick: a probe that takes four seconds
+  // used to cost the budget three, so "thirty seconds" was never thirty.
+  let spent = 0;
+  let answered = 0;
+  let unanswered = 0;
+  let sawProcess = false;
+
+  return {
+    tick: function () {
+      const now = clock();
+      const elapsed = now - lastTick;
+      lastTick = now;
+
+      const seen = probe();
+      if (seen && seen.known) {
+        answered++;
+        if (seen.windows > 0) return { verdict: 'window' };
+        if (seen.processes > 0) sawProcess = true;
+        spent += elapsed;
+      } else {
+        // Nothing was learned, so nothing is charged.
+        unanswered++;
+      }
+
+      const outOfBudget = spent >= budgetMs;
+      const outOfPatience = now - started >= hardLimitMs;
+      if (!outOfBudget && !outOfPatience) return null;
+
+      if (unanswered > answered) {
+        return { verdict: 'unclear', answered: answered, unanswered: unanswered };
+      }
+      return {
+        verdict: sawProcess ? 'no-window' : 'never-started',
+        seconds: Math.round((now - started) / 1000),
+      };
+    },
+    stats: function () {
+      return { spent: spent, answered: answered, unanswered: unanswered, sawProcess: sawProcess };
+    },
+  };
+}
+
+// What can be seen of the browser right now.
+//
+//   known     - whether the question could be answered at all
+//   processes - Playwright browser processes running
+//   windows   - how many of those are actually showing a window
+//
+// The three are kept apart on purpose. The old version returned one boolean,
+// so "there is no window" and "the probe did not answer" were the same value,
+// and a slow machine could be told its browser had never opened. They are
+// different facts and they deserve different answers.
+//
+// One command returns both counts: asking twice would double the cost of the
+// most expensive thing in this loop.
+/**
+ * Turns the probe's two numbers into the shape the watchdog reads.
+ *
+ * Anything that is not two numbers means the answer did not arrive intact, and
+ * an answer that did not arrive must never read as "nothing is running" - that
+ * conflation is the whole bug this replaced.
+ */
+function parseWindowProbe(stdout) {
+  const unknown = { known: false, processes: 0, windows: 0 };
+  const parts = String(stdout == null ? '' : stdout).trim().split(/\s+/);
+  if (parts.length < 2) return unknown;
+  const processes = Number(parts[0]);
+  const windows = Number(parts[1]);
+  if (!Number.isFinite(processes) || !Number.isFinite(windows)) return unknown;
+  if (processes < 0 || windows < 0 || windows > processes) return unknown;
+  return { known: true, processes: processes, windows: windows };
+}
+
+function inspectBrowserWindows() {
+  const unknown = { known: false, processes: 0, windows: 0 };
   try {
     if (process.platform === 'win32') {
       const probe = spawnSync(
@@ -548,17 +739,33 @@ function browserWindowIsUp() {
         [
           '-NoProfile',
           '-Command',
-          "@(Get-Process chrome,msedge -ErrorAction SilentlyContinue | " +
-            "Where-Object { $_.Path -like '*ms-playwright*' -and $_.MainWindowHandle -ne 0 }).Count",
+          "$p = @(Get-Process chrome,msedge -ErrorAction SilentlyContinue | " +
+            "Where-Object { $_.Path -like '*ms-playwright*' }); " +
+            "$w = @($p | Where-Object { $_.MainWindowHandle -ne 0 }); " +
+            'Write-Output ("{0} {1}" -f $p.Count, $w.Count)',
         ],
-        { encoding: 'utf8', windowsHide: true, timeout: 8000 }
+        { encoding: 'utf8', windowsHide: true, timeout: WINDOW_PROBE_TIMEOUT_MS }
       );
-      return Number(String(probe.stdout || '').trim()) > 0;
+      // A timeout, a missing shell, or a non-zero exit all mean the same thing:
+      // nothing was learned. Only a well formed answer counts as knowing.
+      if (probe.error || probe.status !== 0) return unknown;
+      return parseWindowProbe(probe.stdout);
     }
-    const probe = spawnSync('ps', ['-A', '-o', 'command'], { encoding: 'utf8', timeout: 8000 });
-    return /ms-playwright/.test(String(probe.stdout || ''));
+
+    const probe = spawnSync('ps', ['-A', '-o', 'command'], {
+      encoding: 'utf8',
+      timeout: WINDOW_PROBE_TIMEOUT_MS,
+    });
+    if (probe.error || probe.status !== 0) return unknown;
+    const running = String(probe.stdout || '')
+      .split('\n')
+      .filter(function (line) {
+        return line.indexOf('ms-playwright') !== -1;
+      }).length;
+    // ps cannot see windows, so a running browser is taken at its word here.
+    return { known: true, processes: running, windows: running };
   } catch (err) {
-    return true; // cannot tell - do not block the user
+    return unknown;
   }
 }
 
@@ -650,6 +857,89 @@ function reportSecrets(replacements) {
   console.log('');
 }
 
+// One keypress, no Enter, because the safe answer is the default and getting
+// out of the way should cost nothing.
+//
+// Falls back to the default where there is no terminal to read keys from - a
+// CI job, a pipe, an assistant running the command - rather than waiting for
+// an answer that will never arrive.
+function askKey(question, keys, fallback) {
+  return new Promise((resolve) => {
+    const allowed = keys.map((k) => k.toLowerCase());
+    if (!process.stdin.isTTY || !process.stdin.setRawMode) return resolve(fallback);
+    process.stdout.write(question);
+
+    const finish = (answer) => {
+      process.stdin.removeListener("data", onKey);
+      try {
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+      } catch (err) {
+        /* nothing more to do */
+      }
+      process.stdout.write(answer + String.fromCharCode(10));
+      resolve(answer);
+    };
+
+    const onKey = (chunk) => {
+      const key = String(chunk);
+      // In raw mode Ctrl-C arrives as a keystroke rather than a signal, so it
+      // has to be turned back into one. Sent as a signal rather than exiting
+      // here, because exiting would cut off whatever is still buffered - and
+      // it must not be read as an answer either: stopping is not "keep going".
+      if (key === String.fromCharCode(3)) {
+        process.stdin.removeListener('data', onKey);
+        try {
+          process.stdin.setRawMode(false);
+          process.stdin.pause();
+        } catch (err) {
+          /* nothing more to do */
+        }
+        process.stdout.write(String.fromCharCode(10));
+        process.kill(process.pid, 'SIGINT');
+        return;
+      }
+      if (key === String.fromCharCode(13) || key === String.fromCharCode(10)) return finish(fallback);
+      const pressed = key.toLowerCase();
+      if (allowed.indexOf(pressed) === -1) return; // an unknown key: keep waiting
+      finish(pressed);
+    };
+
+    try {
+      process.stdin.setRawMode(true);
+    } catch (err) {
+      return resolve(fallback);
+    }
+    process.stdin.resume();
+    process.stdin.on("data", onKey);
+  });
+}
+
+// Removing a recording means removing what was remembered about it too, or
+// the saved results of a file that no longer exists stay behind for ever.
+function deleteRecording(name) {
+  const relative = path.join("tests", name).split(path.sep).join("/");
+  try {
+    fs.unlinkSync(path.join(TESTS_DIR, name));
+  } catch (err) {
+    return { ok: false, name: name, why: err.message };
+  }
+
+  try {
+    const api = require(path.join(PACKAGE_DIR, "kryptheon-fixture.js"));
+    const all = api.readBaselines(api.BASELINE_FILE);
+    const keys = recordings.baselineKeysForSpec(all, relative);
+    if (keys.length) {
+      for (const key of keys) delete all[key];
+      fs.writeFileSync(api.BASELINE_FILE, JSON.stringify(all, null, 2) + String.fromCharCode(10), "utf8");
+    }
+  } catch (err) {
+    // The recording is gone either way, and a leftover baseline is not worth
+    // failing the command over.
+  }
+  return { ok: true, name: name, file: relative };
+}
+
 function askYesNo(question) {
   return new Promise((resolve) => {
     if (!process.stdin.isTTY) return resolve(false);
@@ -668,6 +958,24 @@ function askYesNo(question) {
   });
 }
 
+// A typed answer, for questions whose answers are not single letters.
+function askLine(question) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) return resolve("");
+    const readline = require("readline");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      try {
+        process.stdin.pause();
+      } catch (err) {
+        /* nothing to do */
+      }
+      resolve(String(answer));
+    });
+  });
+}
+
 // Ending on a logout means the next run starts somewhere else. Almost nobody
 // wants that, so ask.
 async function offerToDropLogout(relativeFile) {
@@ -694,6 +1002,37 @@ async function offerToDropLogout(relativeFile) {
   return true;
 }
 
+// Codegen writes whatever identified the element at the moment it was clicked,
+// which on a page of live figures means the figures end up in the selector. Say
+// so, and say nothing when there is nothing to say.
+// Codegen records the wrong keystrokes along with the right ones, so a typo
+// corrected on the second attempt becomes a wrong login performed on every
+// run. This takes those out and says what it took, because a tool that edits
+// your recording without telling you is worse than one that leaves the mess.
+function tidyRecording(relativeFile) {
+  const source = readSpec(relativeFile);
+  if (source === null) return [];
+  const result = cleanup.cleanRecording(source);
+  if (!result.removed.length) return [];
+  if (!writeSpec(relativeFile, result.source)) return [];
+  return result.removed;
+}
+
+// Said after the file has its name, with the other closing notes, so the
+// order on screen matches the order things happened in.
+function reportTidying(removed) {
+  for (const line of cleanup.describeCleanup(removed)) console.log(line);
+  return removed || [];
+}
+
+function reportFragileSelectors(relativeFile) {
+  const source = readSpec(relativeFile);
+  if (source === null) return [];
+  const findings = selectors.findFragileSelectors(source);
+  for (const line of selectors.describeFragileSelectors(findings)) console.log(line);
+  return findings;
+}
+
 function reportReplayRisks(relativeFile) {
   const source = readSpec(relativeFile);
   if (source === null) return [];
@@ -734,16 +1073,23 @@ async function finaliseRecording(outFile, context) {
     // this point. Take it out before doing anything else with the file.
     const secrets = takeOutSecrets(outFile);
 
+    // After the secrets, deliberately. By this point a password is an
+    // environment variable rather than a literal, so nothing that is said
+    // about a field that was typed twice can put the value back on screen.
+    const tidied = tidyRecording(outFile);
+
     const named = await nameRecording(outFile);
     console.log('');
     console.log('  Saved to ' + named);
     console.log('  Run it any time with:  kryptheon check');
     console.log('');
 
+    reportTidying(tidied);
     reportSecrets(secrets);
     keepArtefactsOutOfGit();
     await offerToDropLogout(named);
     reportReplayRisks(named);
+    reportFragileSelectors(named);
 
     return { code: 0, savedAs: named };
   }
@@ -763,8 +1109,24 @@ async function finaliseRecording(outFile, context) {
     }
   }
 
-  if (ctx.reason === 'no-window') {
-    explainNoWindow();
+  if (ctx.reason === 'no-window' || ctx.reason === 'never-started' || ctx.reason === 'unclear') {
+    // What the browser itself said comes first. It used to be read only when
+    // codegen exited on its own, so on this path a real error - a bad address,
+    // a refused connection - was captured and then thrown away, and the reader
+    // got a list of guesses instead of the answer.
+    reportCodegenSaid(ctx.stderr);
+    const detail = ctx.detail || {};
+    if (ctx.reason === 'unclear') {
+      for (const line of probeUnclearLines(detail.answered || 0, detail.unanswered || 0)) {
+        console.error(line);
+      }
+    } else if (ctx.reason === 'no-window') {
+      for (const line of windowUndetectedLines(detail.seconds || Math.round(WINDOW_TIMEOUT_MS / 1000))) {
+        console.error(line);
+      }
+    } else {
+      explainNoWindow();
+    }
   } else if (ctx.reason === 'signal') {
     console.log('');
     console.log('  Recording stopped before anything was saved.');
@@ -784,6 +1146,125 @@ async function finaliseRecording(outFile, context) {
   return { code: 1, savedAs: null };
 }
 
+// Every record writes another file and check runs all of them, so a first day
+// spent learning the tool leaves a pile of recordings that never worked and a
+// check that reads like a wall of failures. This is the moment asking costs
+// nothing.
+//
+// Keeping is the default because it is the answer that cannot lose work, and
+// the other one is a single keypress away. Where there is no terminal to
+// answer with - a CI job, an assistant running the command - nothing is asked
+// and nothing is deleted: a question nobody can see is not a question.
+async function askAboutExisting(names) {
+  if (!names.length || !process.stdin.isTTY) return false;
+
+  for (const line of recordings.existingRecordingsQuestion(names.length)) console.log(line);
+  const answer = await askKey("  Keep or replace? [K/r] ", ["k", "r"], "k");
+  if (answer !== "r") return false;
+
+  console.log("");
+  console.log("  They will be deleted once this new recording is saved.");
+  return true;
+}
+
+// The old recordings, once the new one is safely on disk. The new file is
+// never in this list, but it is checked by name anyway - deleting the thing
+// just recorded is the one mistake here that cannot be undone.
+function dropOldRecordings(names, savedAs) {
+  const keep = path.basename(String(savedAs || ""));
+  const gone = [];
+  for (const name of names) {
+    if (path.basename(name) === keep) continue;
+    const result = deleteRecording(name);
+    if (result.ok) gone.push(name);
+  }
+  if (!gone.length) return gone;
+  console.log("  Removed " + recordings.plural(gone.length, "older recording") + ":");
+  for (const name of gone) console.log("    " + path.join("tests", name));
+  console.log("");
+  return gone;
+}
+
+// --- remove -----------------------------------------------------------------
+//
+// Recordings pile up. Without a way to take one out, the only way to stop a
+// half-finished experiment being run for ever is to know where the files live
+// and delete one by hand.
+
+function listRecordings(names) {
+  console.log("");
+  console.log("  " + recordings.plural(names.length, "recording") + " in this project:");
+  console.log("");
+  names.forEach((name, i) => {
+    console.log("    " + String(i + 1).padStart(2) + "  " + path.join("tests", name));
+  });
+  console.log("");
+}
+
+async function remove(name) {
+  const names = listSpecFiles();
+  if (!names.length) {
+    console.log("");
+    console.log("  There are no recordings to remove.");
+    console.log("");
+    return 0;
+  }
+
+  let choice;
+  if (name) {
+    choice = recordings.chooseFromList(names, name);
+  } else {
+    listRecordings(names);
+    if (!process.stdin.isTTY) {
+      console.log("  To remove one, run:  kryptheon remove <name>");
+      console.log("");
+      return 0;
+    }
+    const answer = await askLine("  Which one? [number, a for all, Enter to cancel] ");
+    choice = recordings.chooseFromList(names, answer);
+  }
+
+  if (choice.action === "cancel") {
+    console.log("");
+    console.log("  Nothing was removed.");
+    console.log("");
+    return 0;
+  }
+  if (choice.action === "unclear") {
+    console.error("");
+    console.error("  " + choice.why + ": " + JSON.stringify(choice.said));
+    console.error("  Run \"kryptheon remove\" on its own to see the list.");
+    console.error("");
+    return 1;
+  }
+
+  const gone = [];
+  const failed = [];
+  for (const target of choice.names) {
+    const result = deleteRecording(target);
+    if (result.ok) gone.push(target);
+    else failed.push(result);
+  }
+
+  console.log("");
+  if (gone.length) {
+    console.log("  Removed " + recordings.plural(gone.length, "recording") + ":");
+    for (const g of gone) console.log("    " + path.join("tests", g));
+    console.log("");
+    console.log(
+      gone.length === 1
+        ? "  Its saved result was removed too, so nothing is left behind."
+        : "  Their saved results were removed too, so nothing is left behind.",
+    );
+    console.log("");
+  }
+  for (const f of failed) {
+    console.error("  Could not remove " + path.join("tests", f.name) + ": " + f.why);
+    console.error("");
+  }
+  return failed.length ? 1 : 0;
+}
+
 async function record(url) {
   if (!url) {
     console.error('');
@@ -806,6 +1287,9 @@ async function record(url) {
 
   if (!ensureBrowser()) return 1;
 
+  const existingBefore = listSpecFiles();
+  const replaceExisting = await askAboutExisting(existingBefore);
+
   const hadTestsDir = fs.existsSync(TESTS_DIR);
   try {
     fs.mkdirSync(TESTS_DIR, { recursive: true });
@@ -835,15 +1319,19 @@ async function record(url) {
   // wire it up, name it. Runs once, whether codegen exits on its own or we
   // are interrupted.
   let finished = false;
-  const finalise = async (reason) => {
+  const finalise = async (reason, detail) => {
     if (finished) return 1;
     finished = true;
     const outcome = await finaliseRecording(outFile, {
       hadTestsDir: hadTestsDir,
       target: target,
+      detail: detail || null,
       stderr: stderr,
       reason: reason,
     });
+    // Only now, and only if something was actually saved. Deleting first
+    // would mean a recording that went wrong takes the old ones with it.
+    if (replaceExisting && outcome.savedAs) dropOldRecordings(existingBefore, outcome.savedAs);
     return outcome.code;
   };
 
@@ -859,22 +1347,24 @@ async function record(url) {
     // If no window ever appears, stop instead of waiting for someone to kill us.
     // Someone whose window is real but undetectable can turn this off.
     const watchdogOff = !!process.env.KRYPTHEON_FORCE_RECORD;
-    let waited = 0;
+    const watch = createWindowWatch();
     const watchdog = setInterval(() => {
       if (watchdogOff) {
         clearInterval(watchdog);
         return;
       }
-      waited += WINDOW_POLL_MS;
-      if (browserWindowIsUp()) {
+      // A child that has already gone is the close handler's business, not
+      // this one's: it knows the exit code and what was written.
+      if (child.exitCode !== null || child.signalCode !== null) {
         clearInterval(watchdog);
         return;
       }
-      if (waited >= WINDOW_TIMEOUT_MS) {
-        clearInterval(watchdog);
-        stopChild();
-        finalise('no-window').then(resolve);
-      }
+      const outcome = watch.tick();
+      if (!outcome) return;
+      clearInterval(watchdog);
+      if (outcome.verdict === 'window') return;
+      stopChild();
+      finalise(outcome.verdict, outcome).then(resolve);
     }, WINDOW_POLL_MS);
 
     const onSignal = () => {
@@ -1384,6 +1874,9 @@ async function main() {
     case 'check':
       return finishWith(check({ quiet: rest.indexOf('--quiet') !== -1 || rest.indexOf('-q') !== -1 }));
       break;
+    case 'remove':
+    case 'rm':
+      return finishWith(await remove(rest.join(" ").trim()));
     case 'setup-ai':
       return finishWith(setupAi());
     case 'accept':
@@ -1432,6 +1925,23 @@ module.exports = {
   reportReplayRisks: reportReplayRisks,
   offerToDropLogout: offerToDropLogout,
   noWindowLines: noWindowLines,
+  windowUndetectedLines: windowUndetectedLines,
+  probeUnclearLines: probeUnclearLines,
+  createWindowWatch: createWindowWatch,
+  inspectBrowserWindows: inspectBrowserWindows,
+  parseWindowProbe: parseWindowProbe,
+  codegenComplaints: codegenComplaints,
+  reportFragileSelectors: reportFragileSelectors,
+  tidyRecording: tidyRecording,
+  reportTidying: reportTidying,
+  remove: remove,
+  deleteRecording: deleteRecording,
+  dropOldRecordings: dropOldRecordings,
+  askAboutExisting: askAboutExisting,
+  askKey: askKey,
+  WINDOW_TIMEOUT_MS: WINDOW_TIMEOUT_MS,
+  WINDOW_HARD_LIMIT_MS: WINDOW_HARD_LIMIT_MS,
+  WINDOW_POLL_MS: WINDOW_POLL_MS,
   classifyFetchError: classifyFetchError,
   normaliseRecordUrl: normaliseRecordUrl,
   isLocalAddress: isLocalAddress,