staysfixed 0.6.2 → 0.7.1

package/src/v2/check.js

@@ -32,6 +32,7 @@ import { createHash } from 'node:crypto';
 import { promisify } from 'node:util';
 
 import { StaysFixedError, messageOf } from '../core/errors.js';
+import { warn, detail } from '../core/log.js';
 import { findConfigFile, rootForConfig } from '../core/paths.js';
 import { sha256 } from '../core/hash.js';
 
@@ -43,6 +44,13 @@ import { runCheck, makeCheckEvents } from './run.js';
 import { proveCause } from './cause.js';
 import { whatChanged } from './rank.js';
 
+import { attachWatcher, watchOptionsFrom } from './watch/index.js';
+import { guardTheScreen, describeGuard } from './watch/focus.js';
+import {
+  isOffScreen, moveWindowByPid, offScreen, windowBoundsByPid, withoutTakingTheScreen,
+} from './watch/window.js';
+import { onAppStarted, stillOpen } from './adapters/isolate.js';
+
 import { processAdapter } from './adapters/process.js';
 import { sourceAdapter } from './adapters/source.js';
 import { httpAdapter } from './adapters/http.js';
@@ -65,6 +73,9 @@ const exec = promisify(execFile);
 /** @typedef {import('./run.js').LiveBuild} LiveBuild */
 /** @typedef {import('./run.js').WalkRequest} WalkRequest */
 /** @typedef {import('./run.js').CheckEvents} CheckEvents */
+/** @typedef {import('./watch/index.js').PanelOptions} PanelOptions */
+/** @typedef {import('./watch/index.js').WatchFlags} WatchFlags */
+/** @typedef {import('./adapters/isolate.js').OpenedApp} OpenedApp */
 
 /**
  * What a check hands back.
@@ -107,6 +118,8 @@ const exec = promisify(execFile);
  * @property {string} [product]
  * @property {CheckEvents} [events]
  * @property {AbortSignal} [signal]
+ * @property {WatchFlags} [watch]   What the person typed about the live panel. The settings
+ *                                  file has its say too, and this is merged over it.
  */
 
 /** The adapters compiled into every copy, in the order the engine trusts them. Reading the code is free, so it is first. */
@@ -264,8 +277,14 @@ export async function check(options = {}) {
   const events = options.events ?? makeCheckEvents();
   /** @type {Project|null} */
   let project = null;
+  /** @type {ScreenMinder|null} */
+  let screen = null;
   try {
     project = await openProject(options);
+    // Before a single thing is opened. Everything this run puts on somebody's screen —
+    // the live panel, the desktop app under check — goes through here, and so does the
+    // promise that none of it takes the screen off the person using the machine.
+    screen = await mindTheScreen(project, events);
     const verdict = await runCheck({
       store: project.store,
       product: project.product,
@@ -283,6 +302,11 @@ export async function check(options = {}) {
       events,
       signal: options.signal,
     });
+    // The screen is given back before the answer is written, so anything the guard had
+    // to do lands in the sentence a person reads rather than in a log line after it.
+    const minded = screen ? await screen.handBack() : null;
+    if (minded) verdict.summary = `${verdict.summary} ${minded}`;
+
     // The real ledger, door by door, before anything says how much was covered. The loop
     // only knows how many doors it read out of the source and that no journey named one;
     // this reads what every capture of this build actually touched and works out which
@@ -296,6 +320,17 @@ export async function check(options = {}) {
     // confirmation is what lets a caller tell "it went there and found nothing" from
     // "it checked something else and found nothing", and those are not the same answer.
     if (project.target) outcome.target = project.target;
+
+    // The live window was told the engine's verdict the moment the loop finished — before
+    // the gates were applied to it, before the waived findings were taken out, and before
+    // the coverage sentence went on the end. Left there, a window would show a greener,
+    // shorter answer than the terminal beside it, and the two would disagree about the same
+    // run. So it is told again, with the settled one, and only then put away.
+    events.emit({ type: 'check:done', at: events.elapsed(), message: outcome.summary, verdict: outcome });
+    if (screen) {
+      await screen.finish();
+      screen = null;
+    }
     return outcome;
   } catch (e) {
     const outcome = blocked(options, e);
@@ -305,9 +340,28 @@ export async function check(options = {}) {
     // a folder of its own behind as its parting gesture.
     const store = openStore({ root: projectRootFor(options) });
     if (storeExists(store)) await settle(outcome, store, outcome.product);
+    // And the window hears it too. Without this a check that was blocked leaves a window
+    // sitting there saying "running" for the rest of the day, which is the one thing worse
+    // than no window: it looks like a check that is still going rather than one that never
+    // got anywhere.
+    events.emit({ type: 'check:done', at: events.elapsed(), message: outcome.summary, verdict: outcome });
     return outcome;
   } finally {
+    // A check that threw is exactly when a scratch app is left standing on somebody's
+    // screen and a guard is left polling for it, so this runs whatever happened.
+    if (screen) await screen.finish().catch(() => {});
     if (project) await project.close();
+    // Everything this run opened has to be gone. `project.close` tears the adapters down
+    // and each of them releases its own isolations; if anything is still on the books
+    // after that, the tool has left a copy of somebody's app running, and that is worth
+    // saying out loud rather than discovering as a second app on the screen.
+    const left = stillOpen();
+    if (left > 0) {
+      warn(
+        `${left} ${left === 1 ? 'copy' : 'copies'} of an app this check opened could not be accounted for at the end. ` +
+          'Look for a stray window before running it again: two copies of one app fight over the same settings and the same identity.',
+      );
+    }
   }
 }
 
@@ -667,7 +721,13 @@ export async function explain(options = {}) {
   }
   if (differences.length > 40) out.push(`  and ${differences.length - 40} more.`);
   if (f.nearFiles?.length) out.push('', `Nearest code: ${f.nearFiles.slice(0, 6).join(', ')}.`);
-  if (f.unwaivable === true) out.push('', `This cannot be recorded as intended by anyone: ${f.unwaivableWhy ?? 'a person has to look at it'}.`);
+  // No full stop of our own: the reason is already a whole sentence and adding one gave the
+  // agent "...costs a real person real money.." on the reply it reads when it is trying to
+  // understand something it is not allowed to waive.
+  if (f.unwaivable === true) {
+    const why = String(f.unwaivableWhy ?? 'a person has to look at it').trim();
+    out.push('', `This cannot be recorded as intended by anyone: ${/[.!?]$/.test(why) ? why : `${why}.`}`);
+  }
   if (f.waivedBecause) out.push('', `Already recorded as intended: ${f.waivedBecause}`);
 
   const pictures = differences.map((d) => d.evidence).filter((/** @type {string|undefined} */ e) => typeof e === 'string' && /\.png$/i.test(e));
@@ -683,6 +743,259 @@ function short(value) {
   return text.length > 200 ? `${text.slice(0, 197)}...` : text;
 }
 
+// ---------------------------------------------------------------------------
+// The screen, while a check is running
+// ---------------------------------------------------------------------------
+
+/**
+ * The kinds of product that put something on somebody's screen.
+ *
+ * Everything else — a command, a library, an HTTP route, source read off disk — opens
+ * nothing at all, and a run made only of those must not so much as ask macOS which
+ * application is in front. Asking is not free: the first time anything on this machine
+ * asks, the person gets a permission dialog, and getting one of those out of a check that
+ * was never going to show them anything is its own small betrayal.
+ *
+ * Windows is deliberately NOT on this list even though it drives a real desktop. That probe
+ * runs on another machine over SSH, so whatever it puts in front of anybody is in front of
+ * somebody else's screen, and nothing here can reach it.
+ *
+ * @type {Set<string>}
+ */
+const PUTS_SOMETHING_ON_THE_SCREEN = new Set(['electron', 'ios', 'android']);
+
+/**
+ * How long to keep looking for the window of an app that has just been started.
+ *
+ * A desktop app takes a second or two to draw its first window, and on a cold machine it
+ * takes longer. There is no event to wait for — the window belongs to the window server,
+ * not to us — so this is looked for, slowly, and given up on without a word.
+ */
+const WAIT_FOR_A_WINDOW_MS = 20_000;
+
+/** How often to look for it. Slow on purpose: nothing here is racing. */
+const LOOK_FOR_A_WINDOW_MS = 400;
+
+/**
+ * Everything this run put on the screen, and the promise to give the screen back.
+ *
+ * Two steps rather than one, and the gap between them is the point: the screen is handed
+ * back the moment the walking stops, and the window is left up long enough to be told the
+ * settled answer.
+ *
+ * @typedef {object} ScreenMinder
+ * @property {() => Promise<string|null>} handBack   Stop guarding, and hand back the one
+ *   sentence worth saying — or null when there is nothing worth saying, which is the normal
+ *   case and the whole rule: a person who was not interrupted is not told about the
+ *   machinery that did not interrupt them.
+ * @property {() => Promise<void>} finish   Put the window away. Safe at any point, safe
+ *   twice, and safe without `handBack` ever having been called.
+ */
+
+/**
+ * Look after the screen for the length of one check.
+ *
+ * Three jobs, and they are one job seen from three sides.
+ *
+ * THE GUARD. `watch/focus.js` watches who is in front and puts the person back the moment
+ * something of ours pushes in front of them. It is the answer to the complaint that
+ * started this: an app the tool opens may come up ONCE, because watching it work is most
+ * of how you come to trust it, and after the person has chosen something else it never
+ * comes forward again. Nothing else in this tool can do that job, because nothing else
+ * knows which applications on this machine belong to the run.
+ *
+ * THE PANEL. `--watch` opens the live view beside the app, and the app is pinned to its
+ * edge so the two of them read as one window.
+ *
+ * OUT OF SIGHT. With no panel, nobody asked to watch anything, so a desktop app this run
+ * starts is moved off every screen once its window appears. It still runs, still answers
+ * the debugging protocol and still photographs — the picture comes from the compositor,
+ * which does not care where the window is — it simply never appears in front of anybody.
+ *
+ * Every part of this is best effort and every failure is swallowed. A machine with no
+ * window server, no accessibility permission or no browser still runs the check; it just
+ * does not get looked after, which is a disappointment and never a failed check.
+ *
+ * @param {Project} project
+ * @param {CheckEvents} events
+ * @returns {Promise<ScreenMinder|null>}
+ */
+async function mindTheScreen(project, events) {
+  const watch = project.watch;
+  const wantsPanel = watch.enabled === true;
+  const couldShow = project.journeys.some((j) => PUTS_SOMETHING_ON_THE_SCREEN.has(String(j.surface)));
+  // Nothing will appear and nobody asked for a window: there is no screen to look after.
+  if (!wantsPanel && !couldShow) return null;
+
+  const guard = guardTheScreen();
+  // Said under --verbose rather than always, because a person who was not interrupted
+  // should not be told about the machinery that did not interrupt them. It is here at all
+  // so that "the guard is running" is something anybody can see rather than take on trust.
+  detail(
+    'The screen guard is watching. Anything this check opens may come to the front once; from the moment you pick something else, it stays behind you.',
+  );
+
+  const watcher = wantsPanel
+    ? await attachWatcher(events, {
+        product: project.product,
+        project: project.root,
+        journeys: project.journeys,
+        watch,
+        dir: project.store.dir,
+        // The panel's own window is ours, so the guard has to know about it — with two
+        // exceptions, and both of them are cases where pushing that window back would be
+        // the tool overruling somebody.
+        //
+        // A BORROWED browser is the person's own. There was no Chrome for Testing here, so
+        // the panel opened in the browser they actually use; claiming it would have the
+        // guard shoving them out of their own tabs every time they clicked into them.
+        //
+        // AND --watch-front is somebody asking, in so many words, for this window in front.
+        // Claiming it would have the guard undoing the flag a second after it was obeyed.
+        onOpen: (browser) => {
+          if (browser.borrowed || watch.foreground === true) return;
+          guard.claim(browser.name);
+        },
+      })
+    : null;
+
+  /** @type {Promise<void>[]} */
+  const placing = [];
+  // Read by the wait below, so a check that ends while an app is still deciding whether
+  // to draw a window does not sit there for another twenty seconds over the arrangement
+  // of a window nobody is going to see.
+  let stopped = false;
+  const stopListening = onAppStarted((app) => {
+    // Claimed the instant the process exists, before it has drawn anything. A moment
+    // later and its first appearance is read as the person choosing it.
+    guard.claim(app.name);
+    events.emit({
+      type: 'note',
+      at: events.elapsed(),
+      message: `${app.label} is open as "${app.name}". It is a scratch copy, on its own settings, and it is not your own install.`,
+    });
+    placing.push(place(app, watcher, events, () => stopped));
+  });
+
+  /** @type {Promise<string|null>|null} */
+  let handingBack = null;
+  /** @type {Promise<void>|null} */
+  let finishing = null;
+
+  const handBack = () => {
+    handingBack ??= (async () => {
+      stopped = true;
+      stopListening();
+      await guard.release();
+      const line = describeGuard(guard.report());
+      if (line) events.emit({ type: 'note', at: events.elapsed(), message: line });
+      await Promise.allSettled(placing);
+      return line;
+    })();
+    return handingBack;
+  };
+
+  return {
+    handBack,
+    finish: () => {
+      finishing ??= (async () => {
+        await handBack();
+        if (watcher) {
+          try {
+            await watcher.stop();
+          } catch {
+            // A window that will not close is never a reason to change a verdict.
+          }
+          // The claim this whole arrangement makes — that the window never held the check
+          // up — is worth a number rather than trust. Under --verbose, because a person who
+          // is not asking how it went does not need to be told.
+          const health = watcher.open() ? watcher.health() : null;
+          // Silence here is the worst answer: somebody asked to watch this and got
+          // nothing, with no idea whether the window failed or they typed it wrong. Every
+          // way this can go actually WRONG says so in its own words as it happens, so the
+          // only case left for this line is the one nothing else covers: a window called
+          // off because it was going to be closed the moment it arrived.
+          if (!health && watch.keepOpen === false) {
+            warn(
+              'You asked to watch this and no window came up. With --no-keep-open, a window still opening when the check finishes is ' +
+                'called off, because it would only be closed again a second later. Leave --no-keep-open out and it waits, then comes up ' +
+                'with the finished result on it.',
+            );
+          }
+          if (health) {
+            detail(
+              `The watch window took ${health.delivered} of ${health.pushed} updates` +
+                `${health.dropped > 0 ? `, folded ${health.dropped} away while it was catching up` : ''}` +
+                `${health.stalls > 0 ? `, and gave up on ${health.stalls} that ran past their moment` : ''}` +
+                '. The check waited on none of them.',
+            );
+          }
+        }
+      })();
+      return finishing;
+    },
+  };
+}
+
+/**
+ * Put one just-started desktop app where it belongs.
+ *
+ * With a panel: beside it, both windows pinned to one edge, one shape. Without: out of
+ * sight, because nobody asked to watch anything.
+ *
+ * @param {OpenedApp} app
+ * @param {import('./watch/index.js').Watcher|null} watcher
+ * @param {CheckEvents} events
+ * @param {() => boolean} stopped
+ * @returns {Promise<void>}
+ */
+async function place(app, watcher, events, stopped) {
+  if (watcher) {
+    // The panel knows how to find the window itself, and it is the thing that has to be
+    // moved either way, so the whole arrangement is done on that side.
+    await watcher.snapTo({ pid: app.pid, hasWindow: true }).catch(() => {});
+    return;
+  }
+  const where = await waitForItsWindow(app.pid, stopped);
+  if (stopped()) return;
+  if (!where) return;
+  if (isOffScreen(where)) return;
+  // Moving a window can pull the application it belongs to in front of everything else,
+  // so whoever had the screen gets it straight back.
+  const moved = await withoutTakingTheScreen(async () => moveWindowByPid(app.pid, where, offScreen(where)));
+  if (moved) {
+    events.emit({
+      type: 'note',
+      at: events.elapsed(),
+      message: `Nobody asked to watch this run, so ${app.label} was moved off the screen. It is still running and still being read; it is just not in front of you. Run this with --watch to see it work.`,
+    });
+  } else {
+    detail(`${app.label} could not be moved out of sight, so its window is on the screen. The screen guard will keep it from taking the foreground.`);
+  }
+}
+
+/**
+ * Wait for an app to draw its first window, and give up quietly.
+ *
+ * @param {number} pid
+ * @param {() => boolean} stopped
+ * @returns {Promise<import('../watch/place.js').Bounds|null>}
+ */
+async function waitForItsWindow(pid, stopped) {
+  const deadline = Date.now() + WAIT_FOR_A_WINDOW_MS;
+  for (;;) {
+    if (stopped()) return null;
+    const seen = await windowBoundsByPid(pid);
+    if (seen) return seen;
+    if (Date.now() > deadline || stopped()) return null;
+    await new Promise((resolve) => {
+      const timer = setTimeout(resolve, LOOK_FOR_A_WINDOW_MS);
+      // Never the reason a finished program stays open.
+      if (typeof timer.unref === 'function') timer.unref();
+    });
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Opening a project
 // ---------------------------------------------------------------------------
@@ -704,6 +1017,9 @@ function short(value) {
  * @property {import('./run.js').Walker} walk
  * @property {(reference: BuildFingerprint, ctx: {events?: CheckEvents, signal?: AbortSignal}) => Promise<LiveBuild|null>} bootReference
  * @property {(capture: Capture) => Capture} normalise
+ * @property {PanelOptions} watch   What the settings file and the command line, together,
+ *   said about the live panel. Settled once here so the command line and the MCP server
+ *   cannot disagree about what `--watch` meant.
  * @property {{surface: string, at: string|null}} [target]  Set only when the run was aimed
  *   at one kind of product AND something here can actually drive it.
  * @property {() => Promise<void>} close
@@ -807,6 +1123,9 @@ async function openProject(options) {
     walk,
     bootReference,
     normalise,
+    // The settings file first, then whatever was typed. `--watch` can only ever turn the
+    // panel ON: somebody who did not type it has not said no to it, they have said nothing.
+    watch: watchOptionsFrom(/** @type {{watch?: import('../types.js').WatchOptions|boolean}} */ (config), options.watch ?? null),
     close: async () => {
       for (const done of cleanUps.reverse()) {
         try {
@@ -1211,6 +1530,29 @@ async function readConfig(configFile) {
 // Which build is which
 // ---------------------------------------------------------------------------
 
+/**
+ * Everything this tool writes about your project, kept out of what your project IS.
+ *
+ * This one line is load-bearing and it was missing, and the bug it caused reached all the
+ * way to the front door. A build is told from another build by what git says is in the
+ * working tree — the diff, plus the list of files git does not know about. Stays Fixed's own
+ * folder is a file git does not know about, and it gains files every single time the tool
+ * runs. So the untracked list changed on every run, the digest changed with it, and every
+ * run of an UNCHANGED project produced a brand new build id.
+ *
+ * The consequences were all silent. Two runs on identical source were two different builds,
+ * so the second could never find the first one's record. A clean checkout was never clean, so
+ * it never got its commit's id, so `--against HEAD` matched nothing and the stored-record
+ * comparison — the fast path the whole design rests on — could not work at all. Measured on
+ * a scratch product: five runs, one unchanged source file, five different build ids and five
+ * runs reporting NOTHING WAS ACTUALLY COMPARED.
+ *
+ * Excluded rather than gitignored, and that difference matters: gitignoring it would fix the
+ * fingerprint and would also throw away the observation files the design says to keep
+ * forever. What a project's own tooling wrote about a project is never part of the project.
+ */
+const NOT_THE_TOOLS_OWN_FOLDER = ':(exclude).staysfixed';
+
 /**
  * The build you have, named by what is actually in it.
  *
@@ -1245,8 +1587,8 @@ async function fingerprintWorkingTree(root, product) {
   // big uncommitted change therefore got the id of the commit it sat on top of; if that
   // commit was the reference, the check compared the build against itself and reported that
   // nothing had changed. Nothing about a diff's size may ever decide whether a change exists.
-  const diff = await gitDigest(root, ['diff', 'HEAD']);
-  const untracked = await gitDigest(root, ['ls-files', '--others', '--exclude-standard']);
+  const diff = await gitDigest(root, ['diff', 'HEAD', '--', NOT_THE_TOOLS_OWN_FOLDER]);
+  const untracked = await gitDigest(root, ['ls-files', '--others', '--exclude-standard', '--', NOT_THE_TOOLS_OWN_FOLDER]);
   if (!diff.ok || !untracked.ok) {
     throw new StaysFixedError(
       `Git could not say what has changed in this working tree, so there is no way to tell this build apart from the last one. ${diff.why ?? untracked.why ?? ''}`.trim(),

package/src/v2/cli.js

@@ -9,9 +9,17 @@
  * NOTHING THAT WORKED THIS MORNING MAY BREAK. Somebody installed this yesterday
  * and has `staysfixed check --guards` in a git hook. So the version 1 commands
  * are not removed, not renamed and not deprecated with a warning: the same flags
- * they always typed still reach the same code. `--pictures`, `--guards` and
- * `--watch` are the version 1 check, exactly as before. `check` with none of
- * them is the difference engine. That is the whole migration.
+ * they always typed still reach the same code. `--pictures` and `--guards` are
+ * the version 1 check, exactly as before. `check` with neither of them is the
+ * difference engine. That is the whole migration.
+ *
+ * `--watch` is the one flag that moved, and deliberately. It opens the live panel
+ * beside whatever is being checked, and that panel is now version 2's — the one
+ * built for a difference engine, which draws journeys, wobble, findings and a
+ * verdict. Version 1's panel drew approved pictures, which this tool no longer
+ * has. `--pictures --watch` and `--guards --watch` still open version 1's panel
+ * over version 1's run, so the only person whose command changed meaning is the
+ * one who typed `--watch` on its own and got a picture check they did not ask for.
  *
  * This module deliberately holds no engine logic. It parses, it delegates, and
  * it says what came back in plain English — which is the one job that has to
@@ -23,6 +31,11 @@ import { say, ok, warn, fail, blank, heading, paint, duration, setLogLevel } fro
 import { openStore } from './store.js';
 import { SHIP_COMMANDS } from './ship.js';
 import { escalationBlock, escalationsFor, productFor, writeEscalations } from './escalate.js';
+// The one reader of the panel flags, shared with version 1 so `--watch-side` cannot come
+// to mean two different things depending on which check you ran. src/cli/index.js imports
+// this file in turn; that circle is safe because nothing here touches it while either
+// module is still being evaluated.
+import { watchFlags } from '../cli/index.js';
 
 /**
  * What comes back from a check. Everything that did not change never appears
@@ -58,19 +71,37 @@ const V2_OPTIONS = [
   ['--escalations <file>', 'Write the handful of things a person has to rule on into a file, in plain English, ready to paste into a closing summary.'],
 ];
 
-/** The version 1 flags, kept working word for word. */
+/**
+ * The version 1 flags, kept working word for word — plus `snap`, which never worked
+ * anywhere.
+ *
+ * `--no-snap` is documented at the top of src/cli/check.js and read there as
+ * `ctx.flags.snap`, and it was in no command's list of known flags, so typing it got
+ * "I do not know the option --no-snap" from both `check` and `walk`. A flag that is
+ * read but never declared is worse than one that does not exist: the code that reads
+ * it looks finished.
+ */
 const V1_SPEC = {
-  booleans: ['guards', 'pictures', 'record', 'report', 'watch', 'watch-front', 'keep-open', 'profile'],
+  booleans: ['guards', 'pictures', 'record', 'report', 'watch', 'watch-front', 'keep-open', 'profile', 'snap'],
   strings: ['watch-side', 'watch-width'],
   arrays: ['only'],
 };
 
+/** @type {[string, string][]} */
+const WATCH_OPTIONS = [
+  ['--watch', 'Open a window beside what is being checked and watch it happen, live. Without this, a desktop app under check is moved off the screen rather than appearing in front of you.'],
+  ['--watch-side <side>', 'Which side of the app the window sits on: left or right. Default right.'],
+  ['--watch-width <px>', 'How wide that window is. Default 480.'],
+  ['--watch-front', 'Let the window come to the front when it opens. Off by default, on purpose.'],
+  ['--no-keep-open', 'Close the window when the check finishes instead of leaving the result up.'],
+  ['--no-snap', 'Leave both windows where they are instead of putting them side by side.'],
+];
+
 /** @type {[string, string][]} */
 const V1_OPTIONS = [
   ['--pictures', 'The version 1 picture check, unchanged.'],
   ['--guards', 'The version 1 guards, unchanged.'],
   ['--only <name>', 'Just this journey, screen or guard. Repeat it for several.'],
-  ['--watch', 'Open the version 1 panel beside your app and watch it happen.'],
 ];
 
 /**
@@ -104,16 +135,17 @@ export const V2_COMMANDS = {
 
   check: {
     summary: 'Prove nothing that already worked has changed. This is the one you run.',
-    usage: 'staysfixed check [--against <ref>] [--paired] [--journeys <source>] [--json]',
+    usage: 'staysfixed check [--against <ref>] [--paired] [--journeys <source>] [--watch] [--json]',
     describe:
-      'Runs your product through the same steps twice, compares it against the build you\nwere last happy with, subtracts anything the product disagrees with itself about,\nand reports only the differences that are left. Nothing that was already the same\nis mentioned at all — that is the point, and it is what keeps the answer short\nenough for an agent to read every word of it.\n\nSaying what you meant to change, and marking a difference as intended, are not\ndone from here. They need the files you expect to touch, and they are checked\nand counted, so they live where an agent works: the staysfixed_intent and\nstaysfixed_waive tools on the MCP server.\n\nThe version 1 picture check is still here: add --pictures, --guards or --watch\nand nothing about your old command changes.',
-    options: [...V2_OPTIONS, ...V1_OPTIONS],
+      'Runs your product through the same steps twice, compares it against the build you\nwere last happy with, subtracts anything the product disagrees with itself about,\nand reports only the differences that are left. Nothing that was already the same\nis mentioned at all — that is the point, and it is what keeps the answer short\nenough for an agent to read every word of it.\n\nSaying what you meant to change, and marking a difference as intended, are not\ndone from here. They need the files you expect to touch, and they are checked\nand counted, so they live where an agent works: the staysfixed_intent and\nstaysfixed_waive tools on the MCP server.\n\nWith --watch it opens a window beside what is being checked and draws the run as\nit happens. Nothing this tool opens is allowed to keep taking your screen: it may\ncome up once, and from the moment you pick something else it stays behind you.\n\nThe version 1 picture check is still here: add --pictures or --guards and nothing\nabout your old command changes.',
+    options: [...V2_OPTIONS, ...WATCH_OPTIONS, ...V1_OPTIONS],
     examples: [
       'staysfixed check',
       'staysfixed check --json',
       'staysfixed check --against v0.13.0',
       'staysfixed check --paired',
       'staysfixed check --surface web --at http://localhost:3000',
+      'staysfixed check --watch',
       'staysfixed check --selfcheck',
       'staysfixed check --pictures        # exactly what version 1 did',
     ],
@@ -298,7 +330,25 @@ function nameOfBuild(build) {
  * @returns {boolean}
  */
 export function wantsVersionOne(ctx) {
-  return ctx.bool('pictures') || ctx.bool('guards') || ctx.bool('watch') || ctx.bool('record');
+  return ctx.bool('pictures') || ctx.bool('guards') || ctx.bool('record');
+}
+
+/**
+ * What the person typed about the live panel.
+ *
+ * The flags themselves are read by version 1's reader, so the two checks cannot drift
+ * apart on what `--watch-side left` means. Only `--no-snap` is added here, and only
+ * because it is the one panel flag whose whole meaning is "change nothing at all" — it
+ * has to be left undefined when it was not typed, so the settings file still decides.
+ *
+ * @param {import('../cli/index.js').CliContext} ctx
+ * @returns {import('./watch/index.js').WatchFlags}
+ */
+function panelFlags(ctx) {
+  /** @type {import('./watch/index.js').WatchFlags} */
+  const wanted = { ...watchFlags(ctx) };
+  if (ctx.flags.snap !== undefined) wanted.snap = ctx.flags.snap === true;
+  return wanted;
 }
 
 /**
@@ -312,9 +362,17 @@ export function wantsVersionOne(ctx) {
  * caller in three getting a silent undefined.
  *
  * @param {import('../cli/index.js').CliContext} ctx
- * @returns {{cwd: string, configFile: string|undefined, against: string|undefined, paired: boolean, journeys: string|undefined, surface: string|undefined, at: string|undefined, only: string[]}}
+ * @returns {{cwd: string, configFile: string|undefined, against: string|undefined, paired: boolean, journeys: string|undefined, surface: string|undefined, at: string|undefined, only: string[], watch: import('./watch/index.js').WatchFlags}}
  */
 export function checkOptions(ctx) {
+  const watch = panelFlags(ctx);
+  // A window to look at and output for a script want opposite things, and one stray
+  // sentence on standard output is a JSON reply that will not parse. Saying so is better
+  // than quietly picking one.
+  if (watch.enabled === true && ctx.bool('json')) {
+    warn('--watch and --json want opposite things: a window to look at, and output a script can read. Carrying on without the window.');
+    watch.enabled = false;
+  }
   return {
     cwd: ctx.cwd,
     configFile: ctx.configFile,
@@ -324,6 +382,7 @@ export function checkOptions(ctx) {
     surface: ctx.str('surface'),
     at: ctx.str('at'),
     only: ctx.list('only'),
+    watch,
   };
 }
 
@@ -636,7 +695,7 @@ function notCheckedBlock(verdict) {
     );
     say(
       paint.grey(
-        `      A break behind ${unopened === 1 ? 'it' : 'any of them'} is invisible to this tool. Point a journey at ${unopened === 1 ? 'it' : 'them'}, or run the project’s own test suite as journeys.`,
+        `      A break behind ${unopened === 1 ? 'it' : 'any of them'} is invisible to this tool. Point a journey at ${unopened === 1 ? 'it' : 'them'} — name the steps in a journeys file and pass it with --journeys.`,
       ),
     );
   }

package/src/v2/cluster.js

@@ -199,11 +199,20 @@ function buildFinding(signature, members, rename, sources) {
   // Half the differences in a rename are the "vanished" side, so the count of
   // places is the count of pairs, not of rows.
   const count = rename ? Math.max(1, Math.round(members.length / 2)) : members.length;
+  // Do all the members really say the same thing, or only the same KIND of thing?
+  //
+  // The grouping key is coarse on long values on purpose — two five-hundred-character
+  // strings that differ in the middle are one finding, not two hundred — and the sentence
+  // it produced said "The same thing in 12 places" about twelve different values. An agent
+  // reading titles and counts, which is exactly what the design asks it to do, would fix the
+  // one example it was shown and take the count as proof of the other eleven. They are not
+  // the same thing, and now the sentence says so.
+  const identical = members.every((m) => sameValue(m.reference, head.reference) && sameValue(m.candidate, head.candidate));
 
   /** @type {Finding} */
   const finding = {
     id: shortHash(sha256(signature)),
-    title: describe(head, count, rename),
+    title: describe(head, count, rename, identical),
     // Provisional. rank.js replaces this once it knows how far this sits from
     // the edit, which is the only thing that makes the sentence worth reading.
     why: 'Not yet worked out.',
@@ -232,12 +241,20 @@ function buildFinding(signature, members, rename, sources) {
  * @param {Difference} d
  * @param {number} count
  * @param {{from: string, to: string}} [rename]
+ * @param {boolean} [identical]  True when every place in the group moved between the SAME two
+ *                               values. False means the same kind of change with its own
+ *                               values each time, and the sentence has to say which.
  * @returns {string}
  */
-export function describe(d, count, rename) {
+export function describe(d, count, rename, identical = true) {
   const where = CHANNEL_WORDS[d.channel] ?? 'Somewhere';
   const name = smartLeaf(d.path);
-  const spread = count > 1 ? ` The same thing in ${count} places.` : '';
+  const spread =
+    count > 1
+      ? identical
+        ? ` The same thing in ${count} places.`
+        : ` The same kind of change in ${count} places, each with its own values — this is one of them, not all of them.`
+      : '';
 
   if (rename) return `${where}, "${rename.from}" is now called "${rename.to}".${spread}`;