staysfixed 0.7.2 → 0.9.0

package/src/v2/types.js

@@ -152,7 +152,6 @@
  * @property {string|null} [branch]
  * @property {boolean} [dirty]        Working tree had uncommitted changes.
  * @property {string} [artifact]      Path to the built thing. NOT stored here — see store.js.
- * @property {string} [artifactSha256]
  * @property {string} [builtAt]       ISO timestamp.
  * @property {string} [platform]      e.g. 'darwin-arm64'. Comparing across platforms warns.
  * @property {string} [tool]          Stays Fixed version that captured it.
@@ -183,7 +182,12 @@
  * @property {Coverage} [coverage]    What this capture did NOT manage to look at.
  * @property {boolean} [complete]     False when the file was read back torn — see store.js.
  * @property {string} [note]
- * @property {string} [rules]         Id of the normalisation rule set applied, if any.
+ * @property {string} [rules]         Fingerprint of what the normalisation rules DO, if any
+ *                                   were applied. Scope is stamped separately — see rulesScope.
+ * @property {Record<string, string[]>} [rulesScope]
+ *                                   Where each scoped rule applied, by rule id. Absent on
+ *                                   captures written before this was stamped, which is a real
+ *                                   state and says "cannot be compared" rather than "nothing".
  */
 
 // ---------------------------------------------------------------------------
@@ -438,6 +442,12 @@ export {};
  *                                    '$.items.3.name'. Used by sort, round and drop.
  * @property {boolean} [off]          Shipped, documented, and not switched on.
  * @property {string} [whyOff]        Why it is not on by default.
+ * @property {boolean} [machine]      This rule's pattern is a fact about THIS machine — where
+ *                                    the project is checked out, where home is, where the temp
+ *                                    folder went today — rather than a decision about what to
+ *                                    tidy. Two machines running the same rule write the same
+ *                                    placeholder, so the rule is the same rule and its pattern
+ *                                    must not reach the fingerprint. See rulesFingerprint.
  */
 
 /**

package/src/v2/waiver.js

@@ -36,7 +36,6 @@
  * different difference and is reported.
  */
 
-import fsp from 'node:fs/promises';
 import path from 'node:path';
 import crypto from 'node:crypto';
 
@@ -48,9 +47,10 @@ import {
   readIntent,
   readIntentById,
   referenceStamp,
+  fingerprintTree,
+  treeMovedSince,
   readJsonFile,
   writeJsonAtomic,
-  shortDigest,
 } from './intent.js';
 
 /**
@@ -71,10 +71,15 @@ import {
  */
 export const WAIVER_BUDGET = 5;
 
-/** How many differences of one finding go into its fingerprint. Clusters can hold hundreds. */
-const FINGERPRINT_DIFFERENCES = 40;
-
-/** How many dead waivers are kept per product, so a summary can still say what expired. */
+/**
+ * How many dead waivers are kept per product, so a summary can still say what expired.
+ *
+ * LIVE ONES ARE NEVER PRUNED, which is what matters: the budget, the gates and whether a
+ * difference is covered are all worked out from those alone and none of them can be affected
+ * by this number. What it can affect is the sentence "three waivers expired when you
+ * shipped", which counts the dead ones still on disk — so after fifty of them, spread over
+ * ten ships or more, that number is the recent history rather than the whole of it.
+ */
 const KEEP_EXPIRED = 50;
 
 // ---------------------------------------------------------------------------
@@ -94,12 +99,22 @@ const KEEP_EXPIRED = 50;
  * @property {string} fingerprint      Pins the exact difference, values included.
  * @property {string} finding          The finding's own id, when it had one.
  * @property {string} summary          The finding's title, kept so this reads without a check.
- * @property {string[]} paths          The addresses involved, trimmed.
+ * @property {string[]} paths          The first few addresses involved, for somebody reading
+ *                                    this back later. Nothing is decided from them: what the
+ *                                    waiver actually covers is `fingerprint`, which takes in
+ *                                    every difference with no ceiling at all.
  * @property {FindingClass} class      What the engine called it. Always ordinary — see gate 1.
  * @property {string} why              The agent's reason, in its own words.
  * @property {string} intentId
  * @property {string} intentSummary    Copied, so a pruned intent does not orphan the waiver.
  * @property {string} ordering         What was known about when the intent was sealed.
+ * @property {{moved: boolean, knowable: boolean, say: string}} codeSince
+ *                                    Whether the code moved between sealing that intent and
+ *                                    writing this. Not a gate — a moved tree is what an
+ *                                    intent sealed BEFORE the work is supposed to look like.
+ *                                    It is recorded because the alternative is that nobody
+ *                                    reading this waiver a month later can tell whether the
+ *                                    intent describes the build that was actually checked.
  * @property {IntentCoverage} coverage How well it matched what was declared, and how sure.
  * @property {string} at               ISO. Written here, never supplied.
  * @property {string} [by]
@@ -284,6 +299,12 @@ export async function waive(store, what) {
     };
   }
 
+  // The last of the three things intent.js says its tree fingerprint makes checkable. The
+  // other two are gates above; this one cannot be, because both answers are legitimate — an
+  // intent sealed before the work SHOULD see a moved tree, and one sealed after it should
+  // not. So it is written down rather than judged, and a person reading the waiver decides.
+  const codeSince = treeMovedSince(intent, await fingerprintTree(store.root));
+
   /** @type {Waiver} */
   const waiver = {
     id: `waiver-${crypto.randomBytes(5).toString('hex')}`,
@@ -297,6 +318,7 @@ export async function waive(store, what) {
     intentId: intent.id,
     intentSummary: intent.summary,
     ordering: intent.ordering,
+    codeSince,
     coverage,
     at: new Date().toISOString(),
     reference: stamp,
@@ -318,6 +340,7 @@ export async function waive(store, what) {
       `Recorded as intended: ${waiver.summary}`,
       `Your reason, kept: ${why}`,
       `Matched against what you sealed: ${coverage.why} (${coverage.confidence} match)`,
+      codeSince.say,
       '',
       `${left} of your ${WAIVER_BUDGET} waivers left before the next ship. This one is pinned to the exact values that differ and to the reference in force now: if either moves, it stops covering anything.`,
       'This is not approval. Nothing becomes the new normal until a build ships. Say in what you report back that you waived this, and why.',
@@ -371,45 +394,6 @@ export function waiverFor(waivers, finding) {
   return waivers.find((w) => w.fingerprint === fingerprint) ?? null;
 }
 
-/**
- * What the closing summary needs: how many were waived, how many are left, what expired, and one
- * sentence saying so.
- *
- * Waivers must be visible, not quiet. This is the function that makes them so, and a summary
- * that does not use it is hiding something an agent decided on its own.
- *
- * @param {Store} store
- * @param {string} product
- * @returns {Promise<{budget: number, spent: number, left: number, active: Waiver[], expired: number, reference: string, line: string}>}
- */
-export async function countWaivers(store, product) {
-  const stamp = await referenceStamp(store, product);
-  const all = await allWaivers(store, product);
-  const active = all.filter((w) => isLive(w, stamp));
-  const expired = all.length - active.length;
-  const left = Math.max(0, WAIVER_BUDGET - active.length);
-
-  const line =
-    active.length === 0
-      ? `Nothing was waived${expired > 0 ? `, and ${expired} older waiver${expired === 1 ? '' : 's'} died when the reference last moved` : ''}.`
-      : `${active.length} difference${active.length === 1 ? ' was' : 's were'} recorded as intended, not approved: ${active
-          .map((w) => trim(w.summary, 90))
-          .join('; ')}. ${left} of the ${WAIVER_BUDGET} allowed before a person has to look ${left === 1 ? 'is' : 'are'} left.`;
-
-  return { budget: WAIVER_BUDGET, spent: active.length, left, active, expired, reference: stamp, line };
-}
-
-/**
- * Forget a product's waivers. Housekeeping, and the way a test starts clean.
- *
- * @param {Store} store
- * @param {string} product
- * @returns {Promise<void>}
- */
-export async function forgetWaivers(store, product) {
-  await fsp.rm(waiversFile(store, product), { force: true });
-}
-
 /**
  * What a waiver is pinned to.
  *
@@ -418,20 +402,46 @@ export async function forgetWaivers(store, product) {
  * which errs towards a person looking at something they have already seen rather than towards a
  * new break hiding behind an old excuse. That is the right way round.
  *
+ * EVERY difference, and there is deliberately no ceiling on that. Until 2026-08-30 this took
+ * the first forty and stopped, and the sentence above was simply false: a waiver written about
+ * a three-hundred-address finding went on covering it after a value past the fortieth turned
+ * into something else. The addresses were all still there, the title still read the same, the
+ * cluster was still one finding — so the pin matched, the difference was filed as intended, and
+ * nobody was ever shown the one row that had actually broken. That is the whole failure this
+ * file exists to prevent, arriving through the file itself.
+ *
+ * The cost of having no ceiling is a hash over text the caller is already holding in memory,
+ * which is nothing next to being wrong. The tuples are sorted first so that two runs which
+ * found the same differences in a different order still pin to the same thing; the number of
+ * them goes in as well, so a cluster that merely GREW cannot match a waiver written about the
+ * smaller one.
+ *
  * @param {Finding} finding
  * @returns {string}
  */
 export function fingerprintFinding(finding) {
-  const differences = (finding.differences ?? [])
-    .slice(0, FINGERPRINT_DIFFERENCES)
-    .map((d) => [d.path, d.kind, face(d.reference), face(d.candidate)]);
+  const differences = finding.differences ?? [];
+  const hash = crypto.createHash('sha256');
+  /** @param {unknown} part */
+  const eat = (part) => {
+    // JSON escapes every newline inside a value, so a newline is a separator nothing in the
+    // text can forge — two different findings cannot run together into one identical digest.
+    hash.update(`${JSON.stringify(part) ?? 'null'}\n`);
+  };
+
+  eat(finding.title ?? '');
+  eat([...(finding.paths ?? [])].sort());
+  eat(differences.length);
+  const rows = differences.map((d) => JSON.stringify([d.path, d.kind, face(d.reference), face(d.candidate)]));
+  rows.sort();
+  for (const row of rows) hash.update(`${row}\n`);
+
   // A finding with no differences attached, which some callers pass, still has to be pinnable,
   // so the sample and the paths stand in for them.
-  const fallback =
-    differences.length > 0
-      ? []
-      : [finding.sample?.path ?? '', finding.sample?.kind ?? '', face(finding.sample?.reference), face(finding.sample?.candidate)];
-  return shortDigest([finding.title ?? '', [...(finding.paths ?? [])].sort(), differences, fallback]);
+  if (differences.length === 0) {
+    eat([finding.sample?.path ?? '', finding.sample?.kind ?? '', face(finding.sample?.reference), face(finding.sample?.candidate)]);
+  }
+  return hash.digest('hex').slice(0, 16);
 }
 
 // ---------------------------------------------------------------------------

package/src/v2/watch/events.js

@@ -134,6 +134,12 @@ export const SOURCE_WORDS = Object.freeze({
  * @property {number} [total]               How many journeys there are.
  * @property {number} [count]               Whatever this event is counting.
  * @property {number} [watched]             Addresses watched so far, across every journey.
+ * @property {number} [steady]              Only on 'wobble'. Addresses answered the same way
+ *                                          twice, as the engine measured them.
+ * @property {boolean} [measured]           Only on 'wobble'. False when no wobble was taken.
+ * @property {string[]} [findingIds]        Only on 'check:done', and only when the whole
+ *                                          verdict was to hand: every finding that survived,
+ *                                          so a window can drop one that has been waived.
  * @property {number} [durationMs]
  * @property {PanelReference} [reference]   Only on 'reference'.
  * @property {PanelWobble} [wobble]         Only on 'wobble'.
@@ -235,6 +241,9 @@ export const SOURCE_WORDS = Object.freeze({
  * @property {string} summary
  * @property {number} findings
  * @property {number} sealed                How many need a person.
+ * @property {number} newlyUnstable         Addresses that were steady before this change and
+ *                                          are not now. A run can be `ok: false` on these
+ *                                          alone, with no findings at all.
  * @property {number} differencesReal
  * @property {number} differencesNoise
  * @property {number} durationMs
@@ -291,220 +300,30 @@ export const SOURCE_WORDS = Object.freeze({
  */
 
 // ---------------------------------------------------------------------------
-// Saying the new things
+// WHY THERE IS NO say*() FAMILY HERE ANY MORE  (removed 2026-08-30)
 // ---------------------------------------------------------------------------
-
-/**
- * Put an event on a stream that may not be there.
- *
- * Watching is a convenience everywhere in this tool: a check with nobody watching is the
- * normal case, and this keeps that from being an `if` at every call site.
- *
- * @param {EventSink|undefined|null} events
- * @param {PanelEvent} event
- * @returns {void}
- */
-export function say(events, event) {
-  if (!events || typeof events.emit !== 'function') return;
-  try {
-    events.emit(event);
-  } catch {
-    // A stream that cannot take an event is not a reason for a check to stop. It is the
-    // window's problem, and the window is optional.
-  }
-}
-
-/**
- * How many milliseconds in, according to the stream itself when it can say.
- * @param {EventSink|undefined|null} events
- * @returns {number}
- */
-function now(events) {
-  try {
-    return typeof events?.elapsed === 'function' ? events.elapsed() : 0;
-  } catch {
-    return 0;
-  }
-}
-
-/**
- * The plan, said out loud, for a window that opened after the check started.
- *
- * @param {EventSink|undefined|null} events
- * @param {PanelPlanShape} plan
- * @returns {void}
- */
-export function sayPlan(events, plan) {
-  say(events, { type: 'plan', at: now(events), plan });
-}
-
-/**
- * Which build this is being measured against — and, when it is the weaker kind, that it is.
- *
- * @param {EventSink|undefined|null} events
- * @param {PanelReference} reference
- * @returns {void}
- */
-export function sayReference(events, reference) {
-  say(events, {
-    type: 'reference',
-    at: now(events),
-    reference,
-    message: reference.weak
-      ? `${reference.warning || 'This is a weaker check than usual.'} ${reference.how}`.trim()
-      : `Measured against ${reference.name}. ${reference.how}`.trim(),
-  });
-}
-
-/**
- * A journey starting, on a named surface.
- *
- * The surface is the new part. One repository builds a website, a desktop app and a phone app,
- * and a window that only says "walking checkout" leaves a person guessing which of the three
- * they are watching.
- *
- * @param {EventSink|undefined|null} events
- * @param {object} what
- * @param {string} what.journey
- * @param {Surface} [what.surface]
- * @param {string} [what.describe]
- * @param {string} [what.source]
- * @param {string} [what.run]              'a', 'b' or 'single'.
- * @param {number} [what.index]
- * @param {number} [what.total]
- * @returns {void}
- */
-export function sayJourneyStart(events, what) {
-  // "Website: buying one item with a saved card." The surface leads, because on a repository
-  // that builds five products the surface is the thing a person is trying to work out.
-  const where = what.surface ? `${surfaceWord(what.surface)}: ` : '';
-  const doing = what.describe || `walking ${what.journey}`;
-  say(events, {
-    type: 'journey:start',
-    at: now(events),
-    journey: what.journey,
-    describe: what.describe,
-    surface: what.surface,
-    surfaceWord: what.surface ? surfaceWord(what.surface) : undefined,
-    source: what.source,
-    run: what.run,
-    index: what.index,
-    total: what.total,
-    message: `${where}${doing}.`,
-  });
-}
-
-/**
- * The address count rising while a journey is still walking.
- *
- * This is the number that makes the window worth having open: proof that something is
- * happening, on a run where nothing is going to be wrong and there will be nothing to show.
- *
- * @param {EventSink|undefined|null} events
- * @param {string} journey
- * @param {number} count                    Addresses this journey has watched so far.
- * @returns {void}
- */
-export function sayAddresses(events, journey, count) {
-  say(events, { type: 'journey:addresses', at: now(events), journey, count });
-}
-
-/**
- * A journey finished.
- * @param {EventSink|undefined|null} events
- * @param {object} what
- * @param {string} what.journey
- * @param {number} what.count               Addresses watched.
- * @param {number} [what.unstable]          Of those, how many would not sit still.
- * @param {number} [what.durationMs]
- * @param {Surface} [what.surface]
- * @param {string} [what.message]
- * @returns {void}
- */
-export function sayJourneyDone(events, what) {
-  const unstable = Number(what.unstable ?? 0);
-  say(events, {
-    type: 'journey:done',
-    at: now(events),
-    journey: what.journey,
-    surface: what.surface,
-    surfaceWord: what.surface ? surfaceWord(what.surface) : undefined,
-    count: what.count,
-    durationMs: what.durationMs,
-    message:
-      what.message ||
-      `${plural(what.count, 'address', 'addresses')} watched` +
-        (unstable > 0 ? `, ${unstable} of which this build cannot answer the same way twice.` : '.'),
-  });
-}
-
-/**
- * The wobble, measured.
- *
- * Nobody else's tool has this number, so it does not get buried. Everything that would not sit
- * still between two runs of the SAME build was not caused by the change, and is subtracted
- * arithmetically rather than allowed for by a tolerance somebody guessed.
- *
- * @param {EventSink|undefined|null} events
- * @param {PanelWobble} wobble
- * @returns {void}
- */
-export function sayWobble(events, wobble) {
-  const note = wobble.note || wobbleSentence(wobble);
-  say(events, { type: 'wobble', at: now(events), wobble: { ...wobble, note }, count: wobble.unstable, message: note });
-}
-
-/**
- * One finding, the moment it is formed.
- *
- * The finding goes on the stream whole. Cutting it down is the mapper's job and only the
- * mapper's job — two places trimming the same shape is how a window ends up drawing a
- * finding that has already had its findings taken out of it.
- *
- * @param {EventSink|undefined|null} events
- * @param {Finding} finding
- * @returns {void}
- */
-export function sayFinding(events, finding) {
-  say(events, { type: 'finding', at: now(events), finding, message: finding?.title });
-}
-
-/**
- * The coverage, folded — which is mostly the list of what was NOT looked at.
- * @param {EventSink|undefined|null} events
- * @param {Coverage} coverage
- * @returns {void}
- */
-export function sayCoverage(events, coverage) {
-  const gaps = Array.isArray(coverage?.gaps) ? coverage.gaps.length : 0;
-  say(events, {
-    type: 'coverage',
-    at: now(events),
-    coverage,
-    count: gaps,
-    message: coverageSentence(trimCoverage(coverage)),
-  });
-}
-
-/**
- * A plain note, for anything that does not have a shape of its own.
- * @param {EventSink|undefined|null} events
- * @param {string} message
- * @returns {void}
- */
-export function sayNote(events, message) {
-  say(events, { type: 'note', at: now(events), message });
-}
-
-/**
- * The end.
- * @param {EventSink|undefined|null} events
- * @param {Verdict} verdict
- * @returns {void}
- */
-export function sayCheckDone(events, verdict) {
-  say(events, { type: 'check:done', at: now(events), verdict, durationMs: verdict?.durationMs, message: verdict?.summary });
-}
+//
+// This file used to export a second way of talking to a window: sayPlan, sayReference,
+// sayJourneyStart, sayAddresses, sayJourneyDone, sayWobble, sayFinding, sayCoverage,
+// sayNote and sayCheckDone, each one wrapping an emit. Nothing anywhere ever called a
+// single one of them. The engine emits its own plain CheckEvents and `makeMapper` below
+// translates them, so the tool carried two vocabularies for one window and only one of
+// them was wired.
+//
+// They were deleted rather than adopted, and the reason is the paragraph at the top of
+// watch/index.js: the ENGINE works everything out and the PANEL only draws. Every say*()
+// would have had run.js reach for the window's vocabulary at the moment it is meant to be
+// running a difference machine — and it would only have covered the one stream that
+// remembered to call them, where the mapper covers ANY stream, v1's events included. Dead
+// code in a tool whose job is telling the truth about a product is its own small lie: it
+// reads like a supported road and is a road nobody has ever driven down.
+//
+// What was NOT deleted is the vocabulary the window really needs. CLASS_WORDS and
+// SURFACE_NOTES are now embedded in the page by panel.js, exactly the way SURFACE_WORDS
+// and SOURCE_WORDS already were. CLASS_WORDS had to be: the panel was keeping a second
+// hand-written copy of the same map, and the two had already drifted — the panel said "a
+// bug already reported once" where this file says "a bug you already reported", and the
+// panel had no word for 'ordinary' at all.
 
 // ---------------------------------------------------------------------------
 // Trimming — what crosses into the window, and what stays out
@@ -661,6 +480,16 @@ export function trimVerdict(verdict) {
     typeof verdict?.sealed === 'number'
       ? Number(verdict.sealed)
       : list.filter((/** @type {any} */ f) => f?.sealed || isSealedClass(f?.class)).length;
+  // Addresses that used to be steady and are not any more. A run can have NO findings and
+  // still not be a pass because of these, and without the number the window cannot tell that
+  // apart from a run that compared nothing — the two look identical from `ok: false` and a
+  // finding count of nought, and they need opposite sentences.
+  const newlyUnstable =
+    typeof verdict?.newlyUnstable === 'number'
+      ? verdict.newlyUnstable
+      : Array.isArray(verdict?.newlyUnstable)
+        ? verdict.newlyUnstable.length
+        : 0;
   return {
     ok: Boolean(verdict?.ok),
     mode: verdict?.mode ?? 'stored-record',
@@ -668,6 +497,7 @@ export function trimVerdict(verdict) {
     summary: String(verdict?.summary ?? ''),
     findings: counted,
     sealed,
+    newlyUnstable,
     differencesReal: Number(verdict?.differencesReal ?? 0) || 0,
     differencesNoise: Number(verdict?.differencesNoise ?? 0) || 0,
     durationMs: Number(verdict?.durationMs ?? 0) || 0,
@@ -913,10 +743,17 @@ export function makeMapper(plan = {}) {
 
       case 'wobble': {
         announcedWobble = true;
+        // What the ENGINE measured, wherever it said it. `steady` used to be guessed here as
+        // "everything watched so far, minus the unstable ones", and those are two different
+        // populations: `watched` counts what the adapters wrote down, while the wobble is
+        // measured over addresses. The guess therefore claimed addresses had answered the
+        // same way twice that the build had never been asked at. It is kept only as a
+        // fallback, for a stream that says nothing about steadiness at all.
+        const said = numberOr(event.steady);
         const wobble = /** @type {PanelWobble|undefined} */ (event.wobble) ?? {
-          measured: true,
+          measured: event.measured !== false,
           unstable: Number(event.count) || 0,
-          steady: Math.max(0, watched - (Number(event.count) || 0)),
+          steady: said ?? Math.max(0, watched - (Number(event.count) || 0)),
           newlyUnstable: 0,
         };
         return [{ type: 'wobble', at, message: message ?? wobbleSentence(wobble), wobble, count: wobble.unstable }];
@@ -993,6 +830,14 @@ export function makeMapper(plan = {}) {
         type: 'check:done',
         at,
         verdict: trimVerdict(verdict),
+        // WHICH findings, not just how many. A finding only ever ARRIVES at a window; there
+        // was no way to take one away again, and findings are taken away — the engine's
+        // verdict carries every difference it found, and the gates in check.js then remove
+        // the ones an agent has recorded as intended and hand back the settled list. Both
+        // verdicts reach the window, in that order, so a waived finding stayed drawn beside
+        // a terminal that had already stopped reporting it. Naming the survivors is what
+        // lets the window agree: anything drawn that is not on this list is gone.
+        findingIds: findings.map((/** @type {any} */ f) => String(f?.id ?? '')).filter(Boolean),
         durationMs: verdict.durationMs,
         message: message ?? verdict.summary,
       });

package/src/v2/watch/focus.js

@@ -131,19 +131,29 @@ export async function bringForward(name) {
  *  - When one of ours is in front and you have chosen nothing yet, it is left alone. That
  *    first appearance is the point: it is how you see what is happening.
  *
- * @param {{claims?: string[], everyMs?: number, graceMs?: number}} [opts]
+ * `look` and `putBack` exist so this loop can be exercised without a screen. They default to
+ * the two functions above and nothing in the tool passes them; a test does, because the
+ * bookkeeping — what counts as yours, when the screen is given back, how many times it
+ * happened — is the part that has to be right, and it is unreachable behind two calls to
+ * `osascript` that answer differently on every machine and not at all on most of them.
+ *
+ * @param {{claims?: string[], everyMs?: number, graceMs?: number, look?: () => Promise<string|null>, putBack?: (name: string) => Promise<boolean>}} [opts]
  * @returns {ScreenGuard}
  */
 export function guardTheScreen(opts = {}) {
   const everyMs = opts.everyMs ?? LOOK_EVERY_MS;
   const graceMs = opts.graceMs ?? GRACE_MS;
+  const whoIsInFront = opts.look ?? frontmostApp;
+  const putBack = opts.putBack ?? bringForward;
 
   /** @type {Set<string>} everything the tool opened */
   const ours = new Set(opts.claims ?? []);
   /** @type {string|null} the last application the person chose for themselves */
   let yours = null;
   let handedBack = 0;
-  let stopped = process.platform !== 'darwin';
+  // Nothing to guard where there is no window server — unless a caller supplied its own way
+  // of looking, which means it is being driven deliberately rather than left to the machine.
+  let stopped = process.platform !== 'darwin' && !opts.look;
   /** @type {ReturnType<typeof setTimeout>|null} */
   let timer = null;
   const startedAt = Date.now();
@@ -166,14 +176,14 @@ export function guardTheScreen(opts = {}) {
 
   const look = async () => {
     if (stopped) return;
-    const front = await frontmostApp();
+    const front = await whoIsInFront();
     if (front) {
       if (!isOurs(front)) {
         // The person chose this. It is now what "yours" means.
         yours = front;
       } else if (yours && Date.now() - startedAt > graceMs) {
         // Something of ours is in front, and there is somewhere to put you back.
-        const ok = await bringForward(yours);
+        const ok = await putBack(yours);
         if (ok) {
           handedBack += 1;
           detail(`the screen was taken by ${front}; gave it back to ${yours}`);