session-orchestrator 5.3.0 → 5.5.0

package/scripts/lib/validate/check-test-value-bans.mjs

@@ -93,11 +93,27 @@
  *                     pure input→output date function is out of scope by
  *                     construction rather than by exception list.
  *
- *                     NOT flagged: blocks that control the clock (`now:` arg,
- *                     `vi.useFakeTimers` / `vi.setSystemTime`); date literals in
- *                     INPUT position (only `.toBe`/`.toEqual`/`.toStrictEqual`
- *                     expected values are read), which leaves the passthrough
- *                     class (input date === output date) untouched.
+ *                     NOT flagged: blocks that control the clock (`now:`, `{ now }`
+ *                     or a positional `now` — wider than the seam proof, #1478;
+ *                     SCREAMING_CASE `NOW` / `FIXED_NOW` / `NOW_MS` count as
+ *                     clock names too, #1499 item 7 — or a fake timer that pins
+ *                     the DATE: `vi.setSystemTime(<date>)`,
+ *                     `vi.useFakeTimers({ now: <date> })`, also when called in
+ *                     the setup at module level or in a `describe` that
+ *                     encloses the block; a bare `vi.useFakeTimers()` installs
+ *                     at the real clock and pins nothing, #1499 item 8). A
+ *                     handover whose value IS the real clock is no control
+ *                     (#1487): inline (`{ now: Date.now() }`) or through a
+ *                     binding in the same block (`const now = new Date();
+ *                     fn(now)`) or in the shared setup — module level,
+ *                     `describe` body, `beforeEach` (#1489 item 16). A freeze
+ *                     does not exempt a block that hands over a real clock bound
+ *                     at collection time (module level, `describe` body): that
+ *                     value was read before any hook ran (#1499 item 9). Date
+ *                     literals in INPUT position (only `.toBe`/`.toEqual`/
+ *                     `.toStrictEqual` expected values are read), which leaves
+ *                     the passthrough class (input date === output date)
+ *                     untouched.
  *
  * Per-file opt-out: `// @test-value-bans-allowed` in the first 5 lines skips
  * the file entirely (same convention as check-test-fixture-shapes.mjs's
@@ -335,18 +351,98 @@ const keyLiteralRe = (key) => new RegExp(`["'\\\\]+${key}["'\\\\]+\\s*:`);
  * An absolute date pinned as the EXPECTED value of an equality assertion.
  * Input-position date literals (`created_at: '2026-06-21T…'`) do not match —
  * that is what keeps the passthrough class (input date === output date) out.
+ *
+ * CEILING (#1473): a fixed INPUT date that a production TTL ages out later is
+ * not flagged either, on purpose. Measured 2026-09-29 with a shim that moves
+ * `Date.now()` and `new Date()` forward in every vitest worker: the 34 test
+ * files (plus one fixture module) holding a fixed `created_at: '2026-05…09'`
+ * (1,211 tests) stayed green at +120, +365 and +3,650 days, so a rule keyed on
+ * fixed input dates would have reported false positives only. The one real
+ * bomb of that shape, the phase-skip fixture before 6670149c, was green at
+ * -60 days and red at +0 and +120 days under the same shim — and
+ * scanClockBombs() reaches that file since #1476 (alias imports are read) but
+ * stays silent on it: the file hands no clock argument to anything. REVISIT when a
+ * second fixed-input-date bomb lands on main: the class then recurs, and a
+ * clock-shift run of the suite is the check that finds it without guessing.
  */
 const DATE_EXPECTATION =
   /\.(?:toBe|toEqual|toStrictEqual)\(\s*(['"`])(\d{4}-\d{2}-\d{2}(?:[T ][^'"`]*)?)\1\s*\)/;
 
-/** An explicit clock handed to a callee — the seam this ban asks tests to use. */
-const CLOCK_ARG = /\b(?:now|nowMs|nowIso|clock|currentDate)\s*:/;
+/**
+ * A clock-named token not read off an object (`Date.now`, `opts.now`) — shared
+ * head of the patterns below. Group 1 is the name.
+ *
+ * SCREAMING_CASE module constants are clock names too (#1499 item 7): `NOW`,
+ * `NOW_MS`, `NOW_ISO`, and any `<WORD>_`-prefixed form (`FIXED_NOW`,
+ * `FROZEN_NOW`). An `i` flag would not reach them — `_` is a `\w`, so the
+ * lookbehind and the terminators below never see a `FIXED_NOW` boundary.
+ * Measured 2026-10-02 over 722 test files: `NOW` is handed over in 29 files,
+ * `FIXED_NOW` in 10, `NOW_MS` in 5, `NOW_ISO` in 2.
+ */
+const CLOCK_NAME = String.raw`(?<![.\w$])(now|nowMs|nowIso|clock|currentDate|(?:[A-Z][A-Z0-9]*_)*(?:NOW(?:_MS|_ISO)?|CLOCK|CURRENT_DATE))\s*`;
+
+/**
+ * Pass 1, the seam PROOF: a NAMED clock key (`{ now: … }`) — only that shape says
+ * the callee's API takes a clock, whatever value it is handed. Every line it
+ * matches also matches CONTROL_CLOCK_ARG, so a block that proves a seam is never
+ * flagged itself — UNLESS the value it hands over is the real clock (#1487):
+ * then the block proves the seam and is a bomb in the same breath.
+ */
+const SEAM_CLOCK_ARG = new RegExp(`${CLOCK_NAME}:`);
+
+/**
+ * Pass 2, is this block clock-CONTROLLED: any clock handover. Property shorthand
+ * (`{ now }`, `{ repoRoot, now }`) and a positional `now` count too; `Date.now()`
+ * and `const now =` do not. Wider is the safe direction here — it can only
+ * remove findings. Group 2 is the terminator: `:` means the name is a KEY and
+ * the handed-over value follows it; any other terminator means the name IS the
+ * value. A handover only counts when that value is not the real clock — see
+ * {@link handsOverControlledClock}.
+ *
+ * CEILING (#1478): pass 1 reads only the named form, because the wide form also
+ * turns helpers into seams — +20 seamed (file, id) pairs in 15 files
+ * (172 → 192, measured 2026-10-01 @ ffc5929f), e.g. `expectDeny` via a
+ * `{ manifestMtimeMs: now }` fixture. Cost: a file whose ONLY clock handover is
+ * `{ now }` or a positional `now` loses its seam proof and its bombs go unseen.
+ * REVISIT on the first B5 finding whose subject is a helper, or the first CI
+ * `test-value-bans` B5 finding the ±days clock-shift probe shows to be false.
+ */
+const CONTROL_CLOCK_ARG = new RegExp(String.raw`${CLOCK_NAME}(:|,|\}|\))`, 'g');
+
+/** A read of the real wall clock: `Date.now()`, an argument-less `new Date()`, `performance.now()`. */
+const REAL_CLOCK_READ = /\bDate\.now\(\)|\bnew Date\(\s*\)|\bperformance\.now\(\)/;
+
+/**
+ * `const now = <rhs>` / `now = <rhs>` — a clock-named binding (not `==`, not an
+ * arrow `now =>`). Group 1 is the name, group 2 the right-hand side.
+ */
+const CLOCK_BINDING = new RegExp(String.raw`${CLOCK_NAME}=(?![=>])(.*)`);
+
+/**
+ * Freezing the global clock — equally valid control, but not a seam PROOF. Only
+ * the INSTALLERS count: `advanceTimersByTime` / `runAllTimers` move a clock some
+ * installer already faked and freeze nothing on their own, so a block that only
+ * advances timers is controlled exactly when an installer reaches it. Whether an
+ * installer pins the DATE is {@link pinsDate}'s call. Group 1 is the installer.
+ */
+const DATE_PIN_CALL = /\b(useFakeTimers|setSystemTime)\s*\(/g;
 
-/** Freezing the global clock — equally valid control, but not a seam PROOF. */
-const FAKE_TIMER = /\b(?:useFakeTimers|setSystemTime|advanceTimersByTime|runAllTimers)\b/;
+/**
+ * Vitest aliases that resolve to the repo's own modules — source of truth is
+ * `resolve.alias` in vitest.config.mjs (today only `@lib`). CEILING: one entry
+ * per alias, kept by hand; REVISIT when vitest.config.mjs gains an alias — the
+ * parametrised B5 test reads that config and goes red until the key is listed
+ * here. Dynamic imports (`await import('@lib/…')`) are not read in either form.
+ */
+const ALIAS_PREFIXES = ['@lib/'];
 
-/** `import { a, b as c } from './rel.mjs'` — SUT candidates live behind these. */
-const RELATIVE_IMPORT = /import\s+([^;]+?)\s+from\s+['"](\.[^'"]+)['"]/g;
+/** `import { a, b as c } from './rel.mjs'` or `'@lib/x.mjs'` — SUT candidates live behind these. */
+const LOCAL_IMPORT = new RegExp(
+  String.raw`import\s+([^;]+?)\s+from\s+['"]((?:\.|` +
+    ALIAS_PREFIXES.map((p) => p.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')).join('|') +
+    String.raw`)[^'"]+)['"]`,
+  'g',
+);
 
 // ---------------------------------------------------------------------------
 // File enumeration
@@ -564,16 +660,46 @@ function declaredHookSubjects(lines) {
  * @returns {Array<{start: number, end: number}>} half-open [start, end) indices
  */
 function testBlocks(lines) {
-  const OPENER = /^(\s*)(?:it|test)(?:\.\w+)*\s*\(/;
-  const SIBLING = /^\s*(?:it|test|describe)(?:\.\w+)*\s*\(/;
+  return callRanges(lines, /^(\s*)(?:it|test)(?:\.\w+)*\s*\(/, /^\s*(?:it|test|describe)(?:\.\w+)*\s*\(/);
+}
+
+/**
+ * Split a file into `describe(` blocks, segmented like {@link testBlocks} but
+ * with no sibling fallback: a `describe` without its own same-indentation `});`
+ * runs to the end of the file. For its one consumer (B5's setup fake-timer
+ * scope) over-inclusion is NOT safe: a wider `describe` exempts more blocks, so
+ * a fake timer in it hides a sibling describe's time bomb — the false negative
+ * this scoping exists to remove. Ceiling (BV-004): two shapes still widen —
+ * a `describe` closed with options (`}, 10_000);`) runs to end of file, and a
+ * tagged-template `describe.each\`…\`` never matches the opener, so its timer
+ * reads as module level. Measured 2026-10-02 over 722 test files: 0 of the 13
+ * fake-timer files use either shape. Revisit when one appears in a fake-timer
+ * file, or when a B5 miss traces to one.
+ * @param {string[]} lines
+ * @returns {Array<{start: number, end: number}>} half-open [start, end) indices
+ */
+function describeBlocks(lines) {
+  return callRanges(lines, /^(\s*)describe(?:\.\w+)*\s*\(/, null);
+}
+
+/**
+ * Shared segmenter: every line matching `opener` (group 1 = its indentation)
+ * opens a range that ends after the first later line closing at the SAME
+ * indentation (`});`), or before the first `sibling` line, or at end of file.
+ * @param {string[]} lines
+ * @param {RegExp} opener
+ * @param {RegExp|null} sibling
+ * @returns {Array<{start: number, end: number}>} half-open [start, end) indices
+ */
+function callRanges(lines, opener, sibling) {
   const out = [];
   for (let i = 0; i < lines.length; i++) {
-    const m = OPENER.exec(lines[i]);
+    const m = opener.exec(lines[i]);
     if (!m) continue;
     const closer = new RegExp(`^${m[1]}\\}\\)`);
     let end = lines.length;
     for (let j = i + 1; j < lines.length; j++) {
-      if (SIBLING.test(lines[j])) {
+      if (sibling?.test(lines[j])) {
         end = j;
         break;
       }
@@ -588,17 +714,17 @@ function testBlocks(lines) {
 }
 
 /**
- * Identifiers this test file imports from the repo's OWN modules (relative
- * specifiers). These are the subject-under-test candidates for B5; framework
- * (`vitest`) and stdlib (`node:*`) imports are structurally excluded because
- * their specifiers are not relative.
+ * Identifiers this test file imports from the repo's OWN modules (relative or
+ * vitest-alias specifiers). These are the subject-under-test candidates for B5;
+ * framework (`vitest`) and stdlib (`node:*`) imports are structurally excluded
+ * because their specifiers match neither form.
  * @param {string} content
  * @returns {string[]}
  */
 function importedLocalIdentifiers(content) {
   /** @type {Set<string>} */
   const ids = new Set();
-  for (const m of content.matchAll(RELATIVE_IMPORT)) {
+  for (const m of content.matchAll(LOCAL_IMPORT)) {
     const clause = m[1];
     // `{ a, b as c }` → c ; `x` / `* as ns` → x / ns
     for (const part of clause.replace(/[{}]/g, ',').split(',')) {
@@ -612,6 +738,144 @@ function importedLocalIdentifiers(content) {
   return [...ids];
 }
 
+/**
+ * The clock-named bindings in these lines (`const now = Date.now()`,
+ * `now = new Date('2026-01-01')`): per name, whether ANY binding reads the REAL
+ * clock and whether ANY binding does not. Handing a real-clock binding over is
+ * reading the wall clock with an extra step, not controlling it.
+ *
+ * CEILING (#1487): a real-clock value laundered through a non-clock name
+ * (`const t = Date.now(); fn({ now: t })`) still counts as control. REVISIT
+ * when a clock-shift run of the suite finds a bomb fed by that route.
+ * @param {string[]} live non-comment lines
+ * @returns {Map<string, {real: boolean, other: boolean}>}
+ */
+function clockBindings(live) {
+  /** @type {Map<string, {real: boolean, other: boolean}>} */
+  const out = new Map();
+  for (const line of live) {
+    const m = CLOCK_BINDING.exec(line);
+    if (!m) continue;
+    const seen = out.get(m[1]) ?? { real: false, other: false };
+    if (REAL_CLOCK_READ.test(m[2])) seen.real = true;
+    else seen.other = true;
+    out.set(m[1], seen);
+  }
+  return out;
+}
+
+/**
+ * The clock-named names a block hands over as the REAL clock: its own real-clock
+ * bindings, plus the shared setup's (module level, `describe` body,
+ * `beforeEach`) for every name the block does not rebind itself (#1489 item 16:
+ * read block-wise only, `const now = Date.now()` at module level counted as
+ * control and kept a genuine bomb silent).
+ *
+ * A setup name counts only when EVERY setup binding of it reads the real clock.
+ * Setup is file-wide, not per-`describe`, so a name bound to the real clock in
+ * one `beforeEach` and to a fixed date in another is ambiguous for any given
+ * block — read as control, the scan's precision-first direction.
+ * @param {Map<string, {real: boolean, other: boolean}>} own the block's bindings
+ * @param {Map<string, {real: boolean, other: boolean}>} setup the shared setup's bindings
+ * @returns {Set<string>}
+ */
+function realClockNames(own, setup) {
+  /** @type {Set<string>} */
+  const names = new Set();
+  for (const [name, b] of own) if (b.real) names.add(name);
+  for (const [name, b] of setup) if (b.real && !b.other && !own.has(name)) names.add(name);
+  return names;
+}
+
+/**
+ * The value expression starting at `from`, up to the first `,` or closing
+ * bracket at nesting depth 0 (`now: new Date(x), other` → `new Date(x)`).
+ * Brackets inside string literals are not tracked; a cut-short value can only
+ * hide a real-clock read, which leaves the block counted as controlled — the
+ * pre-#1487 behaviour, never a new finding.
+ */
+function valueExpressionAt(line, from) {
+  let depth = 0;
+  for (let i = from; i < line.length; i++) {
+    const c = line[i];
+    if (c === '(' || c === '[' || c === '{') depth++;
+    else if (c === ')' || c === ']' || c === '}') {
+      if (depth === 0) return line.slice(from, i);
+      depth--;
+    } else if (c === ',' && depth === 0) return line.slice(from, i);
+  }
+  return line.slice(from);
+}
+
+/**
+ * True when this line hands over a clock that is NOT the real one: a clock-named
+ * handover (CONTROL_CLOCK_ARG) whose value neither reads the wall clock inline
+ * (`{ now: Date.now() }`) nor names a real-clock binding in the block's scope
+ * (`const now = Date.now(); fn(now)`, see `realClockNames`). #1487: before this,
+ * both shapes counted as control and kept a genuine time bomb silent.
+ * @param {string} line
+ * @param {Set<string>} realClock names bound to the real clock in this block's scope
+ */
+function handsOverControlledClock(line, realClock) {
+  return handoverValues(line).some((v) => !REAL_CLOCK_READ.test(v) && !namesAny(v, realClock));
+}
+
+/**
+ * The values this line hands over as a clock (CONTROL_CLOCK_ARG): after a
+ * `name:` key the expression that follows it, otherwise the name itself.
+ * @param {string} line
+ * @returns {string[]}
+ */
+function handoverValues(line) {
+  return [...line.matchAll(CONTROL_CLOCK_ARG)].map((m) =>
+    m[2] === ':' ? valueExpressionAt(line, m.index + m[0].length) : m[1],
+  );
+}
+
+/**
+ * True when `value` names one of `names` as a whole identifier.
+ * @param {string} value
+ * @param {Iterable<string>} names
+ */
+function namesAny(value, names) {
+  return [...names].some((n) => new RegExp(String.raw`(?<![.\w$])${n}(?![\w$])`).test(value));
+}
+
+/**
+ * True when this line freezes the calendar DATE, not just the timers (#1499
+ * item 8). vitest 4.1 installs `useFakeTimers()` at `this._fakingDate ||
+ * Date.now()` — the real clock unless a date was set first — so only
+ * `setSystemTime(<date>)` or a `useFakeTimers` config naming `now` pins a day;
+ * `{ toFake: ['setTimeout'] }` leaves Date real. A pin whose value reads the wall
+ * clock pins nothing: inline (`setSystemTime(new Date())`, `{ now: Date.now() }`)
+ * or through a clock-named binding the scanner knows reads it
+ * (`const now = new Date(); vi.setSystemTime(now)`, `useFakeTimers({ now })` —
+ * review of ac3ded47). An argument the line cannot read — a variable, a config
+ * spread over lines, a quoted key — counts as a pin: precision first, as
+ * everywhere in B5. CEILING: a pin value laundered through a NON-clock name
+ * (`const t = new Date(); vi.setSystemTime(t)`) still counts — the
+ * {@link clockBindings} ceiling.
+ * @param {string} line
+ * @param {Set<string>} realClock names bound to the real clock in this line's scope
+ */
+function pinsDate(line, realClock) {
+  for (const m of line.matchAll(DATE_PIN_CALL)) {
+    const arg = valueExpressionAt(line, m.index + m[0].length).trim();
+    let value = arg;
+    if (m[1] === 'useFakeTimers') {
+      if (arg === '') continue;
+      if (!arg.startsWith('{') || !arg.endsWith('}')) return true;
+      const key = /(?<![\w$])now(?![\w$])\s*([:,}])?/.exec(arg);
+      if (!key) continue;
+      if (!key[1]) return true;
+      // `now:` hands over the expression after it; shorthand `{ now }` hands over the binding `now`.
+      value = key[1] === ':' ? valueExpressionAt(arg, key.index + key[0].length) : 'now';
+    }
+    if (!REAL_CLOCK_READ.test(value) && !namesAny(value, realClock)) return true;
+  }
+  return false;
+}
+
 /** True when `id` is invoked anywhere in these lines. */
 function callsIdentifier(lines, id) {
   const re = new RegExp(`\\b${id}\\s*\\(`);
@@ -623,8 +887,9 @@ function callsIdentifier(lines, id) {
  *
  * Two passes over the file's `it`/`test` blocks:
  *   1. PROVE the seam — an imported id called from a block that also hands over
- *      an explicit clock argument is clock-seamed. A public API only grows a
- *      `now` parameter because the function reads the clock on its main path.
+ *      a NAMED clock key (SEAM_CLOCK_ARG) is clock-seamed. A public API only
+ *      grows a `now` parameter because the function reads the clock on its
+ *      main path.
  *   2. FLAG — in blocks with NO clock control at all, any equality assertion
  *      pinning an absolute date against such a subject is a time bomb.
  *
@@ -642,33 +907,129 @@ function scanClockBombs(relPath, content, lines) {
   const sutIds = importedLocalIdentifiers(content);
   if (sutIds.length === 0) return findings;
 
-  const blocks = testBlocks(lines).map(({ start, end }) => {
+  const ranges = testBlocks(lines);
+
+  // The setup every block shares (helpers, constants, `describe` bodies,
+  // beforeEach): where an echo may come from, and where a clock may be bound or
+  // frozen for the blocks below it. Never a sibling test — its assertions,
+  // titles and clock literals say nothing about this block's inputs.
+  // CEILING (BV-004): a block without its own same-indentation `});` (a
+  // `}, 10_000);` close, an expression-bodied arrow) runs on to the next sibling
+  // and takes the setup lines in between out of sharedSetup. Both directions
+  // follow: a swallowed `now = Date.now()` hides a finding, a swallowed fake
+  // timer adds one. Measured 2026-10-02 @ 46e6695b over 722 test files: 221 of
+  // 15,644 blocks lack the closer, 1 of them swallows a beforeAll/beforeEach,
+  // none a fake-timer install; 0 blocks are one-line its. REVISIT when a
+  // swallowed setup line binds or freezes a clock — then end such blocks on
+  // their own close instead of the sibling (testBlocks() also feeds B2/B3).
+  /** @type {Set<number>} */
+  const inBlock = new Set();
+  for (const { start, end } of ranges) for (let q = start; q < end; q++) inBlock.add(q);
+  const sharedSetup = lines.filter((_, q) => !inBlock.has(q));
+  const setupLive = sharedSetup.filter((l) => !isCommentLine(l));
+  const setupBindings = clockBindings(setupLive);
+  // A clock frozen in setup (`beforeEach(() => vi.setSystemTime(…))`) controls
+  // every block it reaches, including a `now = Date.now()` bound after it — and
+  // it reaches only the blocks vitest runs it for: all of them from module level,
+  // only its own `describe`'s from inside one. A fake timer in a SIBLING
+  // `describe` exempted every block in the file until 2026-10-02 and kept a
+  // genuine bomb silent (review of 3206ab24). `null` = module level.
+  const describes = describeBlocks(lines);
+  /**
+   * Innermost `describe` holding line q — ranges nest, so the latest start that
+   * still holds it — or `null` at module level.
+   * @param {number} q
+   */
+  const innermostDescribe = (q) => {
+    const holders = describes.filter((d) => d.start <= q && q < d.end);
+    return holders.length > 0 ? holders[holders.length - 1] : null;
+  };
+  const setupRealClock = realClockNames(new Map(), setupBindings);
+  /** @type {Array<{start: number, end: number}|null>} */
+  const setupTimerScopes = [];
+  lines.forEach((l, q) => {
+    if (inBlock.has(q) || isCommentLine(l) || !pinsDate(l, setupRealClock)) return;
+    setupTimerScopes.push(innermostDescribe(q));
+  });
+  /** @param {number} start */
+  const setupFreezes = (start) =>
+    setupTimerScopes.some((d) => d === null || (d.start < start && start < d.end));
+  // A real-clock name bound by a statement of the module itself or of a
+  // `describe` body is read at COLLECTION time, before vitest runs any hook
+  // (#1499 item 9). No freeze, in the setup or in the block, reaches that value,
+  // so a block handing it over is not exempted by one. Every other setup binding
+  // is DEFERRED — a hook callback, or a helper function's body (`validRecord()`,
+  // `writeLock()`), which runs when called, after any freeze: 12 of the 13 setup
+  // real-clock bindings outside a hook were such helper locals (measured
+  // 2026-10-02 over 722 test files, review of ac3ded47). A name qualifies only
+  // with no deferred binding at all — anything else reads as control, the
+  // precision-first direction. "Statement of" is read from indentation: column 0
+  // at module level, the enclosing `describe`'s column + 2 inside one (the
+  // prettier indent of this repo). A misread only moves names OUT of the set: a
+  // deeper or other indent style counts as deferred, and a hook range that
+  // over-extends (a one-line `beforeEach(…);`) does the same. CEILINGS: a
+  // one-line helper (`function f() { const now = Date.now(); … }`) at
+  // `describe`-body indent counts as collection time; a freeze that itself runs
+  // at collection time (a module-level `vi.setSystemTime` above the binding) is
+  // not read. Measured 2026-10-02 over 722 test files: 1 collection-time binding
+  // (tests/hooks/lock-reconcile.test.mjs:24), 0 installers outside a hook or test
+  // block. REVISIT on the first B5 finding traced to either shape.
+  const hooks = callRanges(lines, /^(\s*)(?:before|after)(?:Each|All)\s*\(/, null);
+  const indentOf = (/** @type {string} */ l) => /^\s*/.exec(l)[0].length;
+  /** @param {number} q */
+  const atCollection = (q) => {
+    if (hooks.some((h) => h.start <= q && q < h.end)) return false;
+    const d = innermostDescribe(q);
+    return indentOf(lines[q]) === (d ? indentOf(lines[d.start]) + 2 : 0);
+  };
+  const deferredBindings = clockBindings(
+    lines.filter((l, q) => !inBlock.has(q) && !isCommentLine(l) && !atCollection(q)),
+  );
+  const collectionClock = [...setupBindings]
+    .filter(([name, b]) => b.real && !b.other && !deferredBindings.has(name))
+    .map(([name]) => name);
+
+  const blocks = ranges.map(({ start, end }) => {
     const body = lines.slice(start, end);
     const live = body.filter((l) => !isCommentLine(l));
+    const own = clockBindings(live);
+    const realClock = realClockNames(own, setupBindings);
+    const unfrozen = collectionClock.filter((name) => !own.has(name));
+    const handsOverUnfrozen = live.some((l) => handoverValues(l).some((v) => namesAny(v, unfrozen)));
     return {
       start,
       body,
-      hasClockArg: live.some((l) => CLOCK_ARG.test(l)),
-      hasFakeTimer: live.some((l) => FAKE_TIMER.test(l)),
+      provesSeam: live.some((l) => SEAM_CLOCK_ARG.test(l)),
+      hasClockArg: live.some((l) => handsOverControlledClock(l, realClock)),
+      freezesDate: !handsOverUnfrozen && (setupFreezes(start) || live.some((l) => pinsDate(l, realClock))),
     };
   });
 
   /** @type {Set<string>} */
   const seamed = new Set();
   for (const b of blocks) {
-    if (!b.hasClockArg) continue;
+    if (!b.provesSeam) continue;
     for (const id of sutIds) if (callsIdentifier(b.body, id)) seamed.add(id);
   }
   if (seamed.size === 0) return findings;
 
   for (const b of blocks) {
-    if (b.hasClockArg || b.hasFakeTimer) continue;
+    if (b.hasClockArg || b.freezesDate) continue;
     const subject = [...seamed].find((id) => callsIdentifier(b.body, id));
     if (!subject) continue;
+    const echoSources = [...b.body, ...sharedSetup].filter(
+      (l) => !isCommentLine(l) && !DATE_EXPECTATION.test(l),
+    );
     b.body.forEach((line, k) => {
       if (isCommentLine(line)) return;
       const m = DATE_EXPECTATION.exec(line);
       if (!m) return;
+      // Echo: the pinned value is also an input of this block or its shared setup,
+      // not a clock reading (the CEILING above keeps fixed INPUT dates unflagged on
+      // purpose). CEILING: a real bomb whose date also stands in its own block or
+      // the shared setup (its title, a trailing comment, a helper fixture) is
+      // swallowed; REVISIT when a clock-shift run finds a bomb this scan missed.
+      if (echoSources.some((l) => l.includes(m[2]))) return;
       findings.push({
         file: relPath,
         line: b.start + k + 1,

package/scripts/lib/validate/check-unicode-safety.mjs

@@ -204,6 +204,7 @@ const ALLOWED_EMOJI_CODEPOINTS = new Set([
   0x1f5a5, // 🖥
   0x1f6a6, // 🚦
   0x1f6a8, // 🚨
+  0x1f9ed, // 🧭 (navigator banner line in hooks/on-session-start.mjs — #1462)
   0x2139, //  ℹ
   0x2194, //  ↔
   0x26a0, //  ⚠

package/scripts/lib/validate/check-unwired-features.mjs

@@ -74,7 +74,7 @@
  * a backlog, printed as an aggregate like S4 and enumerated under `--list`.
  *
  * S6 carries no camelCase fallback ON PURPOSE: adding one re-hides both reaper
- * keys, whose camelCase names exist in `orphan-reaper.mjs` as that module's own
+ * keys, whose camelCase names exist in `orphan-reaper/defaults.mjs` as that module's own
  * defaults. A name is not a read.
  *
  * S2 applies to TOP-LEVEL keys only — a nested key reaches code through its

package/scripts/lib/validate/check-vcs-repo-flag.mjs

@@ -41,7 +41,7 @@
  *     a string literal counts only when the command STARTS the literal (after
  *     optional whitespace) AND the literal carries no `${` interpolation. That
  *     second half is what separates
- *     `'  glab ci status --pipeline-id LATEST'` (a real command handed to a
+ *     `'  glab ci status --branch main'` (a real command handed to a
  *     shell) from `` `glab note add spawn error: ${err}` `` (a log message).
  *  4. **The first token after the CLI must be a REAL top-level subcommand** of
  *     that CLI, measured from `gh --help` / `glab --help` (gh 2.86.0,