@reticlehq/server 2.4.0 → 2.6.0

package/dist/events/predicate.js

@@ -1,9 +1,12 @@
-import { ElementState, ReticleCommand, } from '@reticlehq/core';
+import { ElementState, PredicateKind, ReticleCommand, } from '@reticlehq/core';
+import { log } from '../log.js';
+import { bindSpanContext } from '../trace.js';
 import { selectPath, capDepth } from '../session/state-select.js';
+import { describeTestidMiss } from './testid-near-miss.js';
 import { predicateToExpectedLinks } from '../capsule/predicate-to-links.js';
 import { isAmbient, ambientKeyOf } from '../journal/ambient.js';
 import { PredicateSchema, matchValue, evalNet, evalRoute, evalConsole, evalAnimation, evalSignal, evalSettled, } from './predicate-eval.js';
-export { PredicateSchema };
+export { PredicateSchema, PredicateKind };
 async function matchOnce(session, query, state) {
     const res = await session.command(ReticleCommand.MATCH, { query, state });
     if (!res.ok)
@@ -23,7 +26,7 @@ async function evalElement(session, query, state, absent, diagnose) {
     //    silently widening to the whole page is the original false green. So scopeMissing FAILS presence
     //    (on the wait_for path this just keeps polling until the scope appears).
     if (absent) {
-        if (match.scopeMissing === true) {
+        if (true === match.scopeMissing) {
             return { pass: true, evidence: { absent: true, scopeMissing: true } };
         }
         return match.matched
@@ -37,7 +40,7 @@ async function evalElement(session, query, state, absent, diagnose) {
             }
             : { pass: true, evidence: { absent: true } };
     }
-    if (match.scopeMissing === true) {
+    if (true === match.scopeMissing) {
         return {
             pass: false,
             failureReason: `scope resolved to no element — cannot confirm ${subject} is present`,
@@ -96,12 +99,19 @@ async function evalElement(session, query, state, absent, diagnose) {
             };
         }
     }
+    // The testid near-miss: name what IS here, so a typo is one step from fixed rather than a dead
+    // end. reticle_query has always done this; the predicate path had no equivalent. See
+    // testid-near-miss.ts.
+    const present = match.hint?.presentTestids ?? [];
+    const alsoHere = query.testid === undefined ? undefined : describeTestidMiss(query.testid, present);
+    const suffix = alsoHere === undefined || '' === alsoHere ? '' : ` — ${alsoHere}`;
     return {
         pass: false,
-        failureReason: `no element matched ${subject}${state === undefined ? '' : ` in state '${state}'`}`,
-        observed: 'no matching element on the page',
+        failureReason: `no element matched ${subject}${state === undefined ? '' : ` in state '${state}'`}${suffix}`,
+        observed: `no matching element on the page${suffix}`,
         expected: `an element matching ${subject}${state === undefined ? '' : ` in state '${state}'`}`,
         assertion: 'element.present',
+        ...(present.length > 0 ? { evidence: { presentTestids: present } } : {}),
     };
 }
 async function evalState(session, p) {
@@ -117,14 +127,15 @@ async function evalState(session, p) {
     }
     const stores = (res.result ?? {}).stores ?? {};
     const names = Object.keys(stores);
-    const storeName = p.store ?? (names.length === 1 ? names[0] : undefined);
+    const storeName = p.store ?? (1 === names.length ? names[0] : undefined);
     if (storeName === undefined) {
-        return {
-            pass: false,
-            failureReason: names.length === 0
-                ? 'no registered store to read state from'
-                : `multiple stores (${names.join(', ')}); name one with \`store\``,
-        };
+        // Neither of these is a finding about the app. With several stores registered the call simply did
+        // not say which one to read; with none, there is nothing to read at all. No assertion was
+        // evaluated either way, so this is inconclusive rather than failed — see honesty/inconclusive.
+        const reason = 0 === names.length
+            ? 'no registered store to read state from'
+            : `multiple stores (${names.join(', ')}); name one with \`store\``;
+        return { pass: false, failureReason: reason, inconclusive: reason };
     }
     const selection = selectPath(stores[storeName], p.path);
     if (!selection.found) {
@@ -153,31 +164,39 @@ async function evalState(session, p) {
         evidence: { store: storeName, path: p.path, value: capDepth(selection.value, 1) },
     };
 }
+/** The predicate's own event-time floor, if its kind carries one. */
+function predicateSince(predicate) {
+    return 'since' in predicate && 'number' === typeof predicate.since ? predicate.since : 0;
+}
 export async function evaluatePredicate(session, predicate, since = 0, 
 // Compute the (extra-round-trip) near-miss diagnostics on element failures. Default true so a
 // one-shot assert is fully diagnostic; the wait loop passes false on its interim polls (which read
 // only `pass`) and true on the final timeout eval, so a flood no longer pays for a diagnostic nobody
 // reads. Only element/text failures have a near-miss; everything else ignores this.
 diagnose = true) {
-    const events = session.eventsSince(since);
+    // A predicate's own `since` is a TIGHTER event-time floor than the caller's — an agent that took
+    // `since` from the act it just performed is scoping the assertion to that action's aftermath. It is
+    // applied here, once, rather than in each eval: the floor means the same thing for every kind that
+    // reads the event stream, and net/console re-applying it is a no-op.
+    const events = session.eventsSince(Math.max(since, predicateSince(predicate)));
     switch (predicate.kind) {
-        case 'element':
+        case PredicateKind.ELEMENT:
             return evalElement(session, predicate.query, predicate.state, predicate.absent ?? false, diagnose);
-        case 'text':
-            return evalElement(session, { text: predicate.contains }, predicate.visible === true ? ElementState.VISIBLE : undefined, predicate.absent ?? false, diagnose);
-        case 'net':
+        case PredicateKind.TEXT:
+            return evalElement(session, { text: predicate.contains }, true === predicate.visible ? ElementState.VISIBLE : undefined, predicate.absent ?? false, diagnose);
+        case PredicateKind.NET:
             return evalNet(events, predicate);
-        case 'route':
+        case PredicateKind.ROUTE:
             return evalRoute(events, predicate);
-        case 'console':
+        case PredicateKind.CONSOLE:
             return evalConsole(events, predicate);
-        case 'animation':
+        case PredicateKind.ANIMATION:
             return evalAnimation(events, predicate);
-        case 'signal':
+        case PredicateKind.SIGNAL:
             return evalSignal(events, predicate);
-        case 'state':
+        case PredicateKind.STATE:
             return evalState(session, predicate);
-        case 'settled': {
+        case PredicateKind.SETTLED: {
             // Drop events on learned-ambient regions (chat/ticker churn) before the settle check — by ref
             // alone, NOT by attribution: window-attribution ("happened during the action window") is a time
             // heuristic, never causation, so a chat message arriving mid-window must not hold settle open.
@@ -185,7 +204,7 @@ diagnose = true) {
             const settleEvents = counts === undefined ? events : events.filter((e) => !isAmbient(counts, ambientKeyOf(e)));
             return evalSettled(settleEvents, predicate, session.elapsed());
         }
-        case 'allOf': {
+        case PredicateKind.ALL_OF: {
             const results = await Promise.all(predicate.predicates.map((p) => evaluatePredicate(session, p, since, diagnose)));
             const failed = results.find((r) => !r.pass);
             return failed === undefined
@@ -196,14 +215,14 @@ diagnose = true) {
                     evidence: results,
                 };
         }
-        case 'anyOf': {
+        case PredicateKind.ANY_OF: {
             const results = await Promise.all(predicate.predicates.map((p) => evaluatePredicate(session, p, since, diagnose)));
             const passed = results.find((r) => r.pass);
             return passed !== undefined
                 ? { pass: true, evidence: passed.evidence }
                 : { pass: false, failureReason: 'no sub-predicate of anyOf matched', evidence: results };
         }
-        case 'not': {
+        case PredicateKind.NOT: {
             const inner = await evaluatePredicate(session, predicate.predicate, since, diagnose);
             return inner.pass
                 ? { pass: false, failureReason: 'negated predicate unexpectedly held', evidence: inner }
@@ -244,12 +263,12 @@ const COUNT_CONFIRM_MS = 300;
  * must stay that way, or every ordinary wait pays the confirmation delay for nothing.
  */
 function assertsExactCount(predicate) {
-    if (predicate.kind === 'allOf' || predicate.kind === 'anyOf') {
+    if (PredicateKind.ALL_OF === predicate.kind || PredicateKind.ANY_OF === predicate.kind) {
         return predicate.predicates.some(assertsExactCount);
     }
-    if (predicate.kind === 'not')
+    if (PredicateKind.NOT === predicate.kind)
         return assertsExactCount(predicate.predicate);
-    return predicate.kind === 'net' && predicate.count !== undefined;
+    return PredicateKind.NET === predicate.kind && predicate.count !== undefined;
 }
 /**
  * Evaluate now, else wait for it to become true (on each event + a poll) until timeout. `since` is
@@ -263,19 +282,36 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
             failureReason: error instanceof Error ? error.message : String(error),
         });
         let cooldownTimer;
+        /** One-shot re-check timed to when a time-based predicate could first pass. See retryAfterMs. */
+        let hintTimer;
         // An exact-count wait keeps watching after it first reads true — see COUNT_CONFIRM_MS.
         const holdsForCount = assertsExactCount(predicate);
         let confirming = false;
         let confirmTimer;
+        /** Report a wait that could not run, and END it — see guardedCheck. */
+        const failWait = (error) => {
+            log('reticle_wait_failed', {
+                predicate: predicate.kind,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            finish({
+                ...failed(error),
+                failureReason: 'the wait could not be evaluated and was ended rather than left pending: ' +
+                    (error instanceof Error ? error.message : String(error)),
+            });
+        };
         const finish = (result) => {
             if (done)
                 return;
             done = true;
             unsub();
+            unsubDisconnect?.();
             clearInterval(interval);
             clearTimeout(timer);
             if (cooldownTimer !== undefined)
                 clearTimeout(cooldownTimer);
+            if (hintTimer !== undefined)
+                clearTimeout(hintTimer);
             if (confirmTimer !== undefined)
                 clearTimeout(confirmTimer);
             resolve(result);
@@ -305,8 +341,19 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
             // final timeout eval below runs with full diagnostics.
             void evaluatePredicate(session, predicate, since, false)
                 .then((r) => {
-                if (!r.pass)
+                if (!r.pass) {
+                    // A time-based failure knows when it could stop being one — re-check THEN rather than on
+                    // the next blind tick. Without this, every `settled` wait paid up to a full poll interval
+                    // of dead time after the quiet window had already closed: measured at 566–627ms across
+                    // the fleet for a 500ms window, on the call an agent makes after almost every action.
+                    // Additive — the backstop interval below still runs, so a missed hint costs nothing.
+                    const hint = r.retryAfterMs;
+                    if ('number' === typeof hint && hint > 0 && hint < POLL_INTERVAL_MS) {
+                        clearTimeout(hintTimer);
+                        hintTimer = setTimeout(check, hint);
+                    }
                     return;
+                }
                 // "Exactly N" cannot be concluded from a passing sample — the count can still rise. Hold,
                 // re-evaluate WITH diagnostics, and let that second read be the verdict: if an N+1th
                 // arrived in the meantime it now fails, carrying observed/expected rather than a bare no.
@@ -344,10 +391,54 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
                 }, MIN_RECHECK_GAP_MS);
             });
         };
+        /**
+         * Run a re-check so that NOTHING can leave this promise pending.
+         *
+         * `check` is fired from an event listener and an interval, neither of which is inside the
+         * awaited chain. A synchronous throw there reached the process as an uncaughtException; a
+         * rejection reached it as an unhandledRejection. Either way the wait never resolved and the tool
+         * handler never returned — the agent sees a call that simply never comes back.
+         *
+         * This half covers the SYNCHRONOUS throw only. The rejection half is handled inside `check`, by
+         * the `.catch` on its own promise chain — `check` returns void and voids the promise it starts,
+         * so there is nothing to hand back here to await. Said explicitly because the obvious-looking
+         * `if (result instanceof Promise) result.catch(…)` that used to sit here was dead code that read
+         * like the rejection guard, and removing `check`'s own `.catch` as redundant would have restored
+         * the exact hang this exists to prevent.
+         *
+         * That is the exact shape reported from a Plane (Next 14 + MobX) session, which tears the page
+         * session down and rebuilds it on EVERY navigation, so a `{kind:"route"}` predicate always races
+         * a teardown of the very session it is watching: `browser.command ok:true` for the click, and
+         * then no `tool.handler` for that callId, ever.
+         *
+         * A wait that cannot evaluate is a FAILED wait, not an eternal one. It now says so and finishes.
+         */
+        const guardedCheck = () => {
+            try {
+                check();
+            }
+            catch (error) {
+                failWait(error);
+            }
+        };
+        // Bound to the CALL that started this wait. The listener fires from the WebSocket message
+        // handler and the interval from the timer queue — neither is in the awaited chain, so without
+        // this every re-check opened a new call at depth 0 and emitted a `browser.command` with no
+        // `tool.handler`. Measured on one healthy run: 23 such orphans, which is precisely the
+        // documented signature of a HUNG call. A diagnostic that fires on healthy runs is not one.
+        const boundCheck = bindSpanContext(guardedCheck);
         const unsub = session.onEvent(() => {
-            check();
+            boundCheck();
+        });
+        const unsubDisconnect = session.onDisconnect?.(() => {
+            // `observationLost` is what stops this being graded as an app defect. `pass: false` is still
+            // correct — the consequence was not seen to hold — but on its own it reached the verdict rule
+            // as ASSERTION_FAILED, so a reload mid-wait reported "the declared consequence did not hold"
+            // against a healthy component, by file and line. The flag is structured rather than inferred
+            // from this string, because every other `failureReason` here is prose about the APP.
+            finish({ pass: false, failureReason: 'session disconnected', observationLost: true });
         });
-        const interval = setInterval(check, POLL_INTERVAL_MS);
+        const interval = setInterval(boundCheck, POLL_INTERVAL_MS);
         const timer = setTimeout(() => {
             void evaluatePredicate(session, predicate, since)
                 .then((r) => {
@@ -382,11 +473,11 @@ export function waitForPredicate(session, predicate, timeoutMs, since = 0) {
  * green ⇏ this-branch-held, re-checks each branch and keeps the winners.
  */
 export async function provenExpectedLinks(session, predicate, since = 0) {
-    if (predicate.kind === 'allOf') {
+    if (PredicateKind.ALL_OF === predicate.kind) {
         const per = await Promise.all(predicate.predicates.map((p) => provenExpectedLinks(session, p, since)));
         return per.flat();
     }
-    if (predicate.kind === 'anyOf') {
+    if (PredicateKind.ANY_OF === predicate.kind) {
         const per = await Promise.all(predicate.predicates.map(async (p) => (await evaluatePredicate(session, p, since)).pass
             ? provenExpectedLinks(session, p, since)
             : []));

package/dist/events/reconcile.js

@@ -39,7 +39,7 @@ const ZERO_DECIMAL = new Set(['JPY', 'KRW', 'VND']);
 const STATE_FIELDS = new Set(['status', 'state']);
 const ITEM_KEYS = ['items', 'results', 'data', 'records', 'rows', 'entries'];
 function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+    return 'object' === typeof value && value !== null && !Array.isArray(value);
 }
 /** Every object carrying an `id`, at any depth. These are the things a UI renders as rows. */
 export function entitiesIn(node, out = []) {
@@ -102,7 +102,7 @@ function wrongCurrencyMark(text, amounts, expected) {
 }
 function markBefore(text, amount, expected) {
     const at = text.indexOf(amount);
-    if (at === -1)
+    if (-1 === at)
         return undefined; // this rendering is not on screen — try the next
     // Look just before the number, where a symbol or code sits. A window, not the whole page: the
     // point is what is attached to THIS amount.
@@ -167,9 +167,9 @@ export function reconcile(bodies, pageText) {
         // number must appear with a currency marker attached. A non-money number that happens to share a
         // decimal form (a weight, a count) is rendered bare and never reaches the comparison.
         const currency = entity['currency'];
-        if (typeof currency === 'string') {
+        if ('string' === typeof currency) {
             for (const [field, value] of Object.entries(entity)) {
-                if (typeof value !== 'number' || field === 'currency')
+                if (typeof value !== 'number' || 'currency' === field)
                     continue;
                 const printed = majorForms(value, currency);
                 const wrong = wrongCurrencyMark(pageText, printed, currency);
@@ -196,7 +196,7 @@ export function reconcile(bodies, pageText) {
             const others = [...(vocabulary.get(field) ?? [])].filter((v) => v !== value);
             const shown = others.filter((v) => shows(pageText, v));
             const key = `${id}:${field}`;
-            if (shown.length === 0 || seen.has(key))
+            if (0 === shown.length || seen.has(key))
                 continue;
             seen.add(key);
             found.push({

package/dist/events/ring-buffer.js

@@ -1,19 +1,4 @@
-import { EventType, RING_BUFFER_DEFAULTS } from '@reticlehq/core';
-/**
- * The high-volume, low-signal floor. These fire continuously on any live page (count-up text, CSS
- * animation frames, React commits, health heartbeats, scroll) and are the ONLY thing that should be
- * sacrificed when the buffer is full. Everything else — a failed request, a console error, a domain
- * signal, a truncation/blind-spot marker — is scarce evidence a verdict depends on, and a churning
- * region must never be able to push it out of the window.
- */
-const CHURN_TYPES = new Set([
-    EventType.DOM_TEXT,
-    EventType.ANIM_START,
-    EventType.ANIM_END,
-    EventType.RENDER_COMMIT,
-    EventType.PAGE_HEALTH,
-    EventType.SCROLL_POSITION,
-]);
+import { CHURN_TYPES, RING_BUFFER_DEFAULTS } from '@reticlehq/core';
 /** How far forward to look for a churn event to sacrifice before falling back to plain FIFO. */
 const CHURN_SCAN_LIMIT = 256;
 /**
@@ -95,7 +80,7 @@ export class RingBuffer {
                 continue;
             }
             const victim = this.#findChurnAfterHead();
-            if (victim === -1) {
+            if (-1 === victim) {
                 // Buffer genuinely full of high-signal events — fall back to FIFO so it stays bounded.
                 this.#totalBytes -= this.#eventBytes[this.#head] ?? 0;
                 this.#head += 1;

package/dist/events/stale-response.js

@@ -1,11 +1,11 @@
 import { ContradictionKind, EventType } from '@reticlehq/core';
 function pathOf(url) {
     const q = url.indexOf('?');
-    return q === -1 ? url : url.slice(0, q);
+    return -1 === q ? url : url.slice(0, q);
 }
 function queryOf(url) {
     const q = url.indexOf('?');
-    return q === -1 ? '' : url.slice(q + 1);
+    return -1 === q ? '' : url.slice(q + 1);
 }
 /**
  * Parameters that ENUMERATE a collection rather than select within it.
@@ -52,13 +52,13 @@ function flights(events) {
     const issued = new Map();
     const out = [];
     for (const event of events) {
-        const id = typeof event.data['id'] === 'string' ? event.data['id'] : undefined;
+        const id = 'string' === typeof event.data['id'] ? event.data['id'] : undefined;
         if (id === undefined)
             continue;
-        const at = typeof event.t === 'number' ? event.t : 0;
+        const at = 'number' === typeof event.t ? event.t : 0;
         if (event.type === EventType.NET_PENDING) {
-            const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
-            const method = typeof event.data['method'] === 'string' ? event.data['method'] : 'GET';
+            const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
+            const method = 'string' === typeof event.data['method'] ? event.data['method'] : 'GET';
             issued.set(id, { url, method, at });
             continue;
         }

package/dist/events/testid-near-miss.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Turning "no element matched {testid: …}" into something an agent can act on.
+ *
+ * `reticle_query` on a missing testid already returns the testids that ARE present, so a typo is one
+ * step from fixed. The same failure through a PREDICATE — `act_and_wait { until: { kind:'element',
+ * query:{ testid } } }` — said only "no element matched" and stopped, naming nothing.
+ *
+ * The near-miss machinery covered an element in the wrong STATE and a wrong NAME for a role (which
+ * even lists the names it saw). Testid — the anchor this codebase calls the gold standard — had
+ * none, and it is the one agents use most.
+ *
+ * It also just became the highest-traffic failure in the product: putting act_and_wait on the
+ * verification path means agents assert far more, so a failed element assertion is now the common
+ * case rather than the rare one.
+ */
+/**
+ * The "…but these ARE here" clause, or undefined when there is nothing useful to say.
+ *
+ * Returns the empty string when the queried testid is itself present: the miss was then about STATE,
+ * not presence, and "you asked for X; X is present" reads as a contradiction rather than a hint.
+ */
+export declare function describeTestidMiss(wanted: string, present: readonly string[]): string | undefined;

package/dist/events/testid-near-miss.js

@@ -0,0 +1,33 @@
+/**
+ * Turning "no element matched {testid: …}" into something an agent can act on.
+ *
+ * `reticle_query` on a missing testid already returns the testids that ARE present, so a typo is one
+ * step from fixed. The same failure through a PREDICATE — `act_and_wait { until: { kind:'element',
+ * query:{ testid } } }` — said only "no element matched" and stopped, naming nothing.
+ *
+ * The near-miss machinery covered an element in the wrong STATE and a wrong NAME for a role (which
+ * even lists the names it saw). Testid — the anchor this codebase calls the gold standard — had
+ * none, and it is the one agents use most.
+ *
+ * It also just became the highest-traffic failure in the product: putting act_and_wait on the
+ * verification path means agents assert far more, so a failed element assertion is now the common
+ * case rather than the rare one.
+ */
+/** Enough to recognise the one you meant; not so many that a large page floods the message. */
+const MAX_LISTED = 12;
+/**
+ * The "…but these ARE here" clause, or undefined when there is nothing useful to say.
+ *
+ * Returns the empty string when the queried testid is itself present: the miss was then about STATE,
+ * not presence, and "you asked for X; X is present" reads as a contradiction rather than a hint.
+ */
+export function describeTestidMiss(wanted, present) {
+    if (0 === present.length)
+        return undefined;
+    if (present.includes(wanted))
+        return '';
+    const shown = present.slice(0, MAX_LISTED);
+    const rest = present.length - shown.length;
+    const tail = rest > 0 ? `, and ${String(rest)} more` : '';
+    return `testids present here: ${shown.join(', ')}${tail}`;
+}

package/dist/events/unit-mismatch.js

@@ -37,7 +37,7 @@ const SCALES = [100, 1000];
  */
 const ID_PATTERN = /[A-Za-z]{2,}_[A-Za-z0-9]{2,}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}/g;
 function parse(raw) {
-    if (typeof raw !== 'string' || raw.length === 0)
+    if (typeof raw !== 'string' || 0 === raw.length)
         return undefined;
     try {
         return JSON.parse(raw);
@@ -53,12 +53,12 @@ function moneyByEntity(node, into) {
             moneyByEntity(item, into);
         return;
     }
-    if (typeof node !== 'object' || node === null)
+    if (typeof node !== 'object' || null === node)
         return;
     const record = node;
     // An id may arrive as a number (`{"id": 9}`) — normalised so a numeric path segment matches it.
     const raw = record['id'];
-    const id = typeof raw === 'string' ? raw : typeof raw === 'number' ? String(raw) : undefined;
+    const id = 'string' === typeof raw ? raw : 'number' === typeof raw ? String(raw) : undefined;
     if (id !== undefined) {
         for (const [key, value] of Object.entries(record)) {
             if (!MONEY_FIELDS.has(key) || typeof value !== 'number')
@@ -79,9 +79,9 @@ function idsIn(url, body) {
         if (segment.length > 0 && /^\d+$/.test(segment))
             found.add(segment);
     }
-    if (typeof body === 'object' && body !== null) {
+    if ('object' === typeof body && body !== null) {
         for (const value of Object.values(body)) {
-            if (typeof value === 'string')
+            if ('string' === typeof value)
                 for (const id of value.match(ID_PATTERN) ?? [])
                     found.add(id);
         }
@@ -90,7 +90,7 @@ function idsIn(url, body) {
 }
 /** The scale between a known value and a sent one, or undefined when they are consistent. */
 function scaleBetween(known, sent) {
-    if (sent === 0 || known === 0)
+    if (0 === sent || 0 === known)
         return undefined;
     for (const scale of SCALES) {
         // A tolerance, because the major-unit form is a rounded render of the minor one.
@@ -127,11 +127,11 @@ export function findUnitMismatches(events, prior = []) {
     for (const event of events) {
         if (event.type !== EventType.NET_REQUEST)
             continue;
-        const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
+        const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
         const requestBody = parse(event.data['requestBody']);
         // Compare BEFORE recording this call's own response, or a request that echoes its own reply
         // would compare against itself.
-        if (typeof requestBody === 'object' && requestBody !== null) {
+        if ('object' === typeof requestBody && requestBody !== null) {
             const sentFields = requestBody;
             for (const id of idsIn(url, requestBody)) {
                 const fields = known.get(id);

package/dist/flows/affected-tools.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { ReticleTool } from '../tools/tool-names.js';
-import { loadNamedFlows, resolveChangedFiles } from '../cli-flow-commands.js';
+import { loadNamedFlows, resolveChangedFiles } from '../cli/cli-flow-commands.js';
 import { affectedSavedFlows } from './flow-sources.js';
 /**
  * `reticle_affected` — which saved flows must re-verify for a set of changed files.
@@ -40,13 +40,28 @@ export const AFFECTED_TOOLS = [
         },
         handler: async (deps, args) => {
             const files = Array.isArray(args['files'])
-                ? args['files'].filter((f) => typeof f === 'string')
+                ? args['files'].filter((f) => 'string' === typeof f)
                 : [];
-            const since = typeof args['since'] === 'string' ? args['since'] : undefined;
+            const since = 'string' === typeof args['since'] ? args['since'] : undefined;
             const changedFiles = await resolveChangedFiles(files, since);
             const flows = await loadNamedFlows(deps.fs, deps.reticleRoot);
             const result = affectedSavedFlows(flows, changedFiles);
-            return { changedFiles, ...result };
+            // Three different situations produced the same empty answer: no files changed, no flows saved,
+            // and a git ref that resolved to nothing. Only the first means "nothing to re-verify"; the
+            // others mean the question could not be answered, and re-running nothing on that basis is how a
+            // regression ships. Say which one it is.
+            const why = 0 === flows.length
+                ? 'no saved flows exist yet, so nothing COULD be affected — record one with reticle_record then reticle_flow_save'
+                : 0 === changedFiles.length
+                    ? since === undefined && 0 === files.length
+                        ? 'no files were given and no `since` ref was passed, so nothing was compared — pass the files you edited, or a git ref'
+                        : 'nothing changed against that input, so no saved flow needs re-verifying'
+                    : undefined;
+            return {
+                changedFiles,
+                ...result,
+                ...(why === undefined ? {} : { observed: true, note: why }),
+            };
         },
     },
 ];

package/dist/flows/affected.js

@@ -23,7 +23,7 @@ export function affectedFlows(flows, changedFiles) {
     const affected = [];
     const unknownProvenance = [];
     for (const flow of flows) {
-        if (flow.sources === undefined || flow.sources.length === 0) {
+        if (flow.sources === undefined || 0 === flow.sources.length) {
             affected.push(flow.name);
             unknownProvenance.push(flow.name);
             continue;

package/dist/flows/annotate-target.d.ts

@@ -0,0 +1 @@
+export declare function resolveAnnotateTarget(explicit: string | undefined, active: readonly string[]): string;

package/dist/flows/annotate-target.js

@@ -0,0 +1,20 @@
+/**
+ * Which recording an annotation belongs to when the call does not say.
+ *
+ * It used to be the literal name `default`, unconditionally. Reproduced on three apps: an agent that
+ * starts `reticle_record { recordingName: "my-flow" }`, acts, and then annotates without repeating
+ * the name gets `annotate_no_step` — because the steps are in "my-flow" and the annotation went
+ * looking in an empty "default". The agent's rational next move is to record MORE steps, into the
+ * wrong place.
+ *
+ * With exactly one recording in progress there is nothing to disambiguate, so that is the answer.
+ * With several, `default` stays the documented choice: silently picking one of the others would put
+ * an assertion in a flow the agent never named, which is worse than an error.
+ */
+/** The documented fallback name, matching what `reticle_record` starts when given none. */
+const DEFAULT_RECORDING = 'default';
+export function resolveAnnotateTarget(explicit, active) {
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    return 1 === active.length ? (active[0] ?? DEFAULT_RECORDING) : DEFAULT_RECORDING;
+}