fix: sleep past the settle quiet deadline instead of onto it (#1306)

runStableCaptureLoop derived its whole cadence from pollMs =
min(300, max(25, quietMs)), so pollMs === quietMs for every quietMs in
[25, 300]. The loop settles once two identical captures span quietMs, and
the gap it measures is exactly one sleep(pollMs) plus capture time — so
across that entire range "settle at capture 2" rode a 0ms margin.

Node decides that margin, not the UI: setTimeout(n) advances Date.now()
by only n-1 in 0.13% of calls idle and 0.63% under load, because libuv
times the sleep on the monotonic loop clock while now() reads the wall
clock. On an undershoot the loop spends a wasted extra capture and poll
before settling.

The sleep is now deadline-aware: while the quiet deadline is further away
than one poll the cadence is unchanged, so changes are still noticed
promptly; once it is within reach, the loop sleeps to just past it. The
capture that decides settled always spans the window.

Effects: --settle-quiet in [25,300] now settles at capture 2 rather than
2-or-3 by coin flip, and the default 500ms window settles at ~502ms
instead of ~600ms with the same 3 captures. No behaviour change beyond
timing; the quiet-window semantics are identical.

Author: thymikee

src/commands/interaction/runtime/selector-read-stable.test.ts

@@ -43,6 +43,48 @@ test('runtime wait stable settles after two unchanged captures', async () => {
   assert.equal(captures, 3);
 });
 
+test('runtime wait stable wakes past the quiet deadline instead of onto it', async () => {
+  const snapshot = selectorReadSnapshot();
+  const sleeps: number[] = [];
+  let elapsed = 0;
+  const clock = {
+    now: () => elapsed,
+    sleep: async (ms: number) => {
+      sleeps.push(ms);
+      elapsed += ms;
+    },
+  };
+  let captures = 0;
+  const device = createAgentDevice({
+    backend: {
+      platform: 'ios',
+      captureSnapshot: async () => {
+        captures += 1;
+        return { snapshot };
+      },
+    } satisfies AgentDeviceBackend,
+    artifacts: createLocalArtifactAdapter(),
+    sessions: createMemorySessionStore([{ name: 'default', snapshot }]),
+    policy: localCommandPolicy(),
+    clock,
+  });
+
+  // A 300ms quiet window equals the poll cadence, so the second capture is the
+  // one that decides `settled`.
+  const result = await device.selectors.wait({
+    session: 'default',
+    target: { kind: 'stable', quietMs: 300, timeoutMs: 10_000 },
+  });
+
+  assert.equal(result.kind, 'stable');
+  if (result.kind === 'stable') assert.equal(result.captures, 2);
+  // Strictly past the window, never onto it: sleeping exactly 300 would leave
+  // the verdict to ~1ms of setTimeout/Date.now() skew (#1306).
+  assert.equal(sleeps.length, 1);
+  assert.ok(sleeps[0]! > 300, `settling capture must clear the window, slept ${sleeps[0]}ms`);
+  assert.equal(captures, 2);
+});
+
 test('runtime wait stable hints when it settles on a nearly-empty tree', async () => {
   const tinySnapshot = makeSnapshotState([
     {

src/commands/interaction/runtime/stable-capture.ts

@@ -19,6 +19,12 @@ import {
  */
 
 const STABLE_POLL_INTERVAL_MS = 300;
+const STABLE_MIN_POLL_MS = 25;
+// Wake PAST the quiet deadline rather than exactly on it. `setTimeout(n)` can
+// advance `Date.now()` by only n-1 — libuv times the sleep on the monotonic
+// loop clock while `now()` reads the wall clock — so a capture landing on the
+// deadline decides `settled` by sub-millisecond skew rather than by the UI.
+const QUIET_DEADLINE_EPSILON_MS = 2;
 export const DEFAULT_STABLE_QUIET_MS = 500;
 export const DEFAULT_STABLE_TIMEOUT_MS = 10_000;
 // Below this node count a settled tree is suspicious: real app surfaces have
@@ -53,7 +59,7 @@ export async function runStableCaptureLoop(
   // Cadence derives from the quiet window (never slower than the default
   // poll): a caller asking for a 50ms quiet window should not be forced onto a
   // 300ms grid — and tests inject the budget instead of waiting real time.
-  const pollMs = Math.min(STABLE_POLL_INTERVAL_MS, Math.max(25, quietMs));
+  const pollMs = Math.min(STABLE_POLL_INTERVAL_MS, Math.max(STABLE_MIN_POLL_MS, quietMs));
   let captures = 0;
   let lastDigest: string | undefined;
   let lastNodeCount = 0;
@@ -89,7 +95,7 @@ export async function runStableCaptureLoop(
       quietSinceMs = nowMs;
       lastDigest = digest;
       lastNodeCount = capture.snapshot.nodes.length;
-      await sleep(runtime, pollMs);
+      await sleep(runtime, stableCaptureDelayMs({ nowMs, quietSinceMs, quietMs, pollMs }));
       continue;
     }
     if (digest !== lastDigest) {
@@ -106,7 +112,7 @@ export async function runStableCaptureLoop(
         lastCapture,
       };
     }
-    await sleep(runtime, pollMs);
+    await sleep(runtime, stableCaptureDelayMs({ nowMs, quietSinceMs, quietMs, pollMs }));
   }
   return {
     settled: false,
@@ -122,6 +128,24 @@ function isPrivateAxRecovery(verdict: SnapshotQualityVerdict | undefined): boole
   return verdict?.state === 'recovered' && verdict.backend === 'private-ax';
 }
 
+/**
+ * How long to wait before the next capture. While the quiet deadline is still
+ * further away than one poll, keep the cadence so a change is noticed promptly.
+ * Once it is within reach, sleep to just past it instead — the capture that
+ * decides `settled` then always spans the window, rather than landing on the
+ * boundary where clock skew picks the answer (#1306).
+ */
+function stableCaptureDelayMs(params: {
+  nowMs: number;
+  quietSinceMs: number;
+  quietMs: number;
+  pollMs: number;
+}): number {
+  const remainingQuietMs = params.quietSinceMs + params.quietMs - params.nowMs;
+  if (remainingQuietMs > params.pollMs) return params.pollMs;
+  return Math.max(STABLE_MIN_POLL_MS, remainingQuietMs + QUIET_DEADLINE_EPSILON_MS);
+}
+
 // Intentionally does not update the session snapshot: the stable loop captures
 // an interactive-only tree purely as a settle signal, and overwriting the
 // session's richer cached snapshot with the filtered tree would degrade