fix: bound the quiet-deadline sleep by the loop's own budget (P2 review)

The review is right: the epsilon could spend the very capture it exists to
land. With quietMs=300 and timeoutMs=301, capture 1 asked for a 302ms sleep,
woke past the 301ms deadline, and the loop exited with one capture — where
the old 300ms cadence settled. waitedMs could exceed timeoutMs too, and the
recovery-reset branch shared the same helper.

stableCaptureDelayMs now takes the deadline and never wakes past it: the loop
only runs again while now < deadline, so where the budget is the tighter
constraint it wakes just inside it and takes the capture the plain cadence
would have taken. The epsilon still applies whenever the budget has room.

The motivating regression test is also strengthened per review, from asserting
the requested delay is > 300 to modelling the defect itself: an injected clock
whose sleep advances now by ms - 1, asserting the observable two-capture
settle. Each test now catches exactly one defect:

  vs main (bd62502):  undershoot FAILS, boundary passes
  vs addbcc3:         undershoot passes, boundary FAILS
  vs this commit:       both pass

Boundary cases added on both sides of the edge: timeoutMs one millisecond past
the quiet window (settles at capture 2, waitedMs within budget), and equal to
it (cannot settle — the window has to elapse inside the budget).

Author: thymikee

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

@@ -43,23 +43,34 @@ 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[] = [];
+// A clock whose sleep lands `undershootMs` short of what was asked, modelling
+// the real defect: `setTimeout(n)` can advance `Date.now()` by only n-1,
+// because libuv times the sleep on the monotonic loop clock while `now()` reads
+// the wall clock.
+function createUndershootingClock(undershootMs = 1): {
+  now: () => number;
+  sleep: (ms: number) => Promise<void>;
+} {
   let elapsed = 0;
-  const clock = {
+  return {
     now: () => elapsed,
     sleep: async (ms: number) => {
-      sleeps.push(ms);
-      elapsed += ms;
+      elapsed += Math.max(0, ms - undershootMs);
     },
   };
-  let captures = 0;
+}
+
+function createStableCaptureDevice(clock: {
+  now: () => number;
+  sleep: (ms: number) => Promise<void>;
+}) {
+  const snapshot = selectorReadSnapshot();
+  const counter = { captures: 0 };
   const device = createAgentDevice({
     backend: {
       platform: 'ios',
       captureSnapshot: async () => {
-        captures += 1;
+        counter.captures += 1;
         return { snapshot };
       },
     } satisfies AgentDeviceBackend,
@@ -68,21 +79,63 @@ test('runtime wait stable wakes past the quiet deadline instead of onto it', asy
     policy: localCommandPolicy(),
     clock,
   });
+  return { device, counter };
+}
 
+test('runtime wait stable settles at the second capture even when the sleep undershoots', async () => {
   // A 300ms quiet window equals the poll cadence, so the second capture is the
-  // one that decides `settled`.
+  // one that decides `settled` — and a sleep that lands 1ms short must not
+  // change the verdict (#1306).
+  const { device, counter } = createStableCaptureDevice(createUndershootingClock());
+
   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);
+  assert.equal(counter.captures, 2);
+});
+
+test('runtime wait stable still takes its settling capture when the budget barely clears the window', async () => {
+  // One millisecond of budget past the quiet window is enough to settle, and
+  // the deadline-aware sleep must not spend it on the epsilon: overshooting the
+  // deadline would drop the settling capture the plain cadence would have taken.
+  const { device, counter } = createStableCaptureDevice(createFakeClock());
+
+  const result = await device.selectors.wait({
+    session: 'default',
+    target: { kind: 'stable', quietMs: 300, timeoutMs: 301 },
+  });
+
+  assert.equal(result.kind, 'stable');
+  if (result.kind === 'stable') {
+    assert.equal(result.captures, 2);
+    assert.ok(
+      result.waitedMs <= 301,
+      `waitedMs must stay within the budget, got ${result.waitedMs}`,
+    );
+  }
+  assert.equal(counter.captures, 2);
+});
+
+test('runtime wait stable cannot settle when the budget only reaches the quiet deadline', async () => {
+  // The other side of the boundary: the window has to ELAPSE inside the budget,
+  // so a budget equal to it leaves no instant where two captures span it. The
+  // deadline-aware sleep must not manufacture a settle here.
+  const { device } = createStableCaptureDevice(createFakeClock());
+
+  await assert.rejects(
+    () =>
+      device.selectors.wait({
+        session: 'default',
+        target: { kind: 'stable', quietMs: 300, timeoutMs: 300 },
+      }),
+    (error: unknown) =>
+      error instanceof Error &&
+      (error as { details?: { reason?: string } }).details?.reason === 'wait_stable_timeout',
+  );
 });
 
 test('runtime wait stable hints when it settles on a nearly-empty tree', async () => {

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

@@ -95,7 +95,10 @@ export async function runStableCaptureLoop(
       quietSinceMs = nowMs;
       lastDigest = digest;
       lastNodeCount = capture.snapshot.nodes.length;
-      await sleep(runtime, stableCaptureDelayMs({ nowMs, quietSinceMs, quietMs, pollMs }));
+      await sleep(
+        runtime,
+        stableCaptureDelayMs({ nowMs, quietSinceMs, quietMs, pollMs, deadlineMs }),
+      );
       continue;
     }
     if (digest !== lastDigest) {
@@ -112,7 +115,10 @@ export async function runStableCaptureLoop(
         lastCapture,
       };
     }
-    await sleep(runtime, stableCaptureDelayMs({ nowMs, quietSinceMs, quietMs, pollMs }));
+    await sleep(
+      runtime,
+      stableCaptureDelayMs({ nowMs, quietSinceMs, quietMs, pollMs, deadlineMs }),
+    );
   }
   return {
     settled: false,
@@ -134,16 +140,25 @@ function isPrivateAxRecovery(verdict: SnapshotQualityVerdict | undefined): boole
  * 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).
+ *
+ * Bounded by the loop's own budget: it only runs again while `now < deadline`,
+ * so a wake-up past the deadline spends the very capture the epsilon exists to
+ * land. Where the budget is the tighter constraint, wake just inside it.
  */
 function stableCaptureDelayMs(params: {
   nowMs: number;
   quietSinceMs: number;
   quietMs: number;
   pollMs: number;
+  deadlineMs: 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);
+  const cadenceMs =
+    remainingQuietMs > params.pollMs
+      ? params.pollMs
+      : Math.max(STABLE_MIN_POLL_MS, remainingQuietMs + QUIET_DEADLINE_EPSILON_MS);
+  const lastUsefulWakeMs = params.deadlineMs - params.nowMs - 1;
+  return lastUsefulWakeMs > 0 ? Math.min(cadenceMs, lastUsefulWakeMs) : cadenceMs;
 }
 
 // Intentionally does not update the session snapshot: the stable loop captures