refactor(android): encode the monotonic clock in the flush-window mark name

The coordinator's confirmation of cubic's P1 adds the shape the code
should carry: the map is now testImeLastRestoreAtPerfMs, so 'AtMs' no
longer misreads as a wall-clock epoch, and the comment states the
two-clock mechanism (sleep is timed on libuv's monotonic loop clock; a
wall-clock-derived remaining time mixes clocks by construction — the
skew stable-capture.ts documents). One monotonic source for
registration and expiry, no clamp hiding anything.

P3 extension: the abort test now pins the NUMBER the design rests on —
the mark is seeded 1000 ms old so the first wait must derive ~1500, and
after the aborted kill the retry re-derives the same remainder from the
surviving mark. A constant sleep, or an abort that consumed the
evidence, fails on the number.

Co-Authored-By: Apex <noreply@callstack.io>

Author: thymikee

packages/platform-android/src/ime-restore.test.ts

@@ -16,7 +16,7 @@ import {
 import {
   resetAndroidTestImeActivationCacheForTests,
   setAndroidTestImeActiveForTests,
-  testImeLastRestoreAtMs,
+  testImeLastRestoreAtPerfMs,
 } from './ime-state.ts';
 import { fakeImeDeviceAdb, type FakeImeDeviceState } from './ime-device.fixtures.ts';
 
@@ -190,7 +190,7 @@ describe('a close cancelled mid-settle', () => {
     // monotonic timestamp keeps the remaining wait derivable for the next kill-bound caller.
     expect(result).toMatchObject({ restored: true, reason: 'ok' });
     expect([...(host.markerStore.get(STATE_DIR) ?? [])]).toEqual([DEVICE.id]);
-    expect([...testImeLastRestoreAtMs.keys()]).toEqual([DEVICE.id]);
+    expect([...testImeLastRestoreAtPerfMs.keys()]).toEqual([DEVICE.id]);
   });
 
   test('a second close waits out the remaining window before it may return to the kill', async () => {
@@ -234,7 +234,7 @@ describe('a close cancelled mid-settle', () => {
     expect(sleep).toHaveBeenCalledTimes(1);
     expect(sleep.mock.calls[0]?.[0]).toBeGreaterThan(0);
     expect(sleep.mock.calls[0]?.[1]).toBe(second.signal);
-    expect([...testImeLastRestoreAtMs.keys()]).toEqual([]);
+    expect([...testImeLastRestoreAtPerfMs.keys()]).toEqual([]);
     expect([...(host.markerStore.get(STATE_DIR) ?? [])]).toEqual([]);
   });
 
@@ -244,7 +244,7 @@ describe('a close cancelled mid-settle', () => {
     // A window from an earlier aborted close still has most of its budget left when this close's
     // own restore writes again. SettingsState rewrites the whole file, so one wait to the newer
     // write's window persists both writes — the timestamp takes the max, never a second entry.
-    testImeLastRestoreAtMs.set(DEVICE.id, performance.now() - 100);
+    testImeLastRestoreAtPerfMs.set(DEVICE.id, performance.now() - 100);
 
     const result = await withAndroidAdbProvider(
       { exec: fakeImeDeviceAdb(stuckDeviceState()) },
@@ -256,14 +256,14 @@ describe('a close cancelled mid-settle', () => {
     expect(result).toMatchObject({ restored: true, reason: 'ok' });
     expect(sleep).toHaveBeenCalledTimes(1);
     expect(sleep.mock.calls[0]?.[0]).toBeGreaterThan(2_000);
-    expect([...testImeLastRestoreAtMs.keys()]).toEqual([]);
+    expect([...testImeLastRestoreAtPerfMs.keys()]).toEqual([]);
   });
 
   test('a second close after the window already elapsed skips the wait', async () => {
     const host = bindAndroidAdbHostStub();
     await host.imeRecoveryMarkers.write(STATE_DIR, DEVICE.id);
     // A restore whose whole flush window has already passed.
-    testImeLastRestoreAtMs.set(DEVICE.id, performance.now() - 2_501);
+    testImeLastRestoreAtPerfMs.set(DEVICE.id, performance.now() - 2_501);
 
     const result = await withAndroidAdbProvider(
       { exec: fakeImeDeviceAdb(stuckDeviceState()) },
@@ -274,7 +274,7 @@ describe('a close cancelled mid-settle', () => {
 
     expect(result).toEqual({ restored: false, reason: 'not-activated-here' });
     expect(sleep).not.toHaveBeenCalled();
-    expect([...testImeLastRestoreAtMs.keys()]).toEqual([]);
+    expect([...testImeLastRestoreAtPerfMs.keys()]).toEqual([]);
     // Load-bearing on this close: it inspected nothing (not-activated-here), and covering the
     // window a confirmed restore had opened is the only thing that earns clearing this marker.
     expect([...(host.markerStore.get(STATE_DIR) ?? [])]).toEqual([]);
@@ -283,7 +283,7 @@ describe('a close cancelled mid-settle', () => {
   test('an ordinary close never waits on a pending window it cannot race', async () => {
     const host = bindAndroidAdbHostStub();
     await host.imeRecoveryMarkers.write(STATE_DIR, DEVICE.id);
-    testImeLastRestoreAtMs.set(DEVICE.id, performance.now());
+    testImeLastRestoreAtPerfMs.set(DEVICE.id, performance.now());
 
     const result = await withAndroidAdbProvider(
       { exec: fakeImeDeviceAdb(stuckDeviceState()) },
@@ -294,7 +294,7 @@ describe('a close cancelled mid-settle', () => {
     expect(result).toEqual({ restored: false, reason: 'not-activated-here' });
     expect(sleep).not.toHaveBeenCalled();
     // An ordinary close consumes nothing and inspects nothing: both stay for the next caller.
-    expect([...testImeLastRestoreAtMs.keys()]).toEqual([DEVICE.id]);
+    expect([...testImeLastRestoreAtPerfMs.keys()]).toEqual([DEVICE.id]);
     expect([...(host.markerStore.get(STATE_DIR) ?? [])]).toEqual([DEVICE.id]);
   });
 });
@@ -313,7 +313,7 @@ test('an ordinary close restores without any flush wait but registers the window
   expect(sleep).not.toHaveBeenCalled();
   // Registration is what lets a later kill-bound close — including another session's — see the
   // window this restore opened.
-  expect([...testImeLastRestoreAtMs.keys()]).toEqual([DEVICE.id]);
+  expect([...testImeLastRestoreAtPerfMs.keys()]).toEqual([DEVICE.id]);
 });
 
 test("a kill-bound close after another close's restore waits out the registered window", async () => {
@@ -335,7 +335,7 @@ test("a kill-bound close after another close's restore waits out the registered
   // 'ok' with no wait owed — is what this asserts; the clear-not-earned branches live in the
   // cancelled-mid-settle suite, where the first close leaves the marker in place.)
   expect([...(host.markerStore.get(STATE_DIR) ?? [])]).toEqual([]);
-  expect([...testImeLastRestoreAtMs.keys()]).toEqual([DEVICE.id]);
+  expect([...testImeLastRestoreAtPerfMs.keys()]).toEqual([DEVICE.id]);
 
   sleep.mockClear();
   const result = await withAndroidAdbProvider(
@@ -349,7 +349,7 @@ test("a kill-bound close after another close's restore waits out the registered
   expect(result).toEqual({ restored: false, reason: 'not-activated-here' });
   expect(sleep).toHaveBeenCalledTimes(1);
   expect(sleep.mock.calls[0]?.[0]).toBeGreaterThan(0);
-  expect([...testImeLastRestoreAtMs.keys()]).toEqual([]);
+  expect([...testImeLastRestoreAtPerfMs.keys()]).toEqual([]);
 });
 
 test('a shutdown of a physical device restores without any flush wait', async () => {
@@ -423,7 +423,7 @@ test.each([false, true])('startup recovers a stuck orphan with displaced=%s', as
   // The startup path writes `ime set` like any other restore, so it owes the same flush window:
   // a later kill-bound path (close --shutdown or the shutdown runtime) must not land inside it.
   // Registration is synchronous — daemon boot never pays a sleep for the window.
-  expect([...testImeLastRestoreAtMs.keys()]).toEqual([DEVICE.id]);
+  expect([...testImeLastRestoreAtPerfMs.keys()]).toEqual([DEVICE.id]);
   expect(sleep).not.toHaveBeenCalled();
   expect(host.diagnostics).toContainEqual({
     phase: 'android_test_ime_orphan_restored',

packages/platform-android/src/ime-state.ts

@@ -21,26 +21,30 @@ export type AndroidTestImeOwnership = {
 // margin past the cap only has to absorb the AtomicFile rename.
 const SETTINGS_PROVIDER_FLUSH_SETTLE_MS = 2_500;
 
-// Per-device monotonic last-restore timestamps, keyed by serial and read from the process
-// monotonic clock (performance.now), never the wall clock: the flush window is a property of the
-// device's SettingsProvider, not of any host state dir or of the close that performed the
-// restore, and a wall-clock step (VM resume, NTP correction) must never be able to shrink the
-// remaining wait. Every restore only moves the timestamp forward, so it can never consume
-// evidence a later kill needs — the wait is always derived from the newest write, which is also
-// why windows coalesce into one wait rather than stacking. Every path that may `adb emu kill`
-// calls awaitTestImeFlushWindow first; the kill-bound close finalization also consumes the
-// outcome so the pending marker clears only under a completed (or never-owed) wait.
+// Per-device last-restore marks, keyed by serial, timed entirely on the PROCESS MONOTONIC
+// CLOCK (performance.now) — never the wall clock, as the name suffix encodes. sleep() is
+// timed on libuv's monotonic loop clock, so a wall-clock-derived remaining time would mix two
+// clocks by construction (the skew stable-capture.ts documents in prose), and a forward step
+// from NTP or VM resume could make remainingMs negative and release the kill inside the
+// window. One source for both registration and expiry means neither can drift against the
+// other. The flush window is a property of the device's SettingsProvider, not of any host
+// state dir or of the close that performed the restore. Every restore only moves the mark
+// forward, so it can never consume evidence a later kill needs — the wait is always derived
+// from the newest write, which is also why windows coalesce into one wait rather than
+// stacking. Every path that may `adb emu kill` calls awaitTestImeFlushWindow first; the
+// kill-bound close finalization also consumes the outcome so the pending marker clears only
+// under a completed (or never-owed) wait.
 // @internal the map is exported for tests; production touches it only through the helpers here.
-export const testImeLastRestoreAtMs = new Map<string, number>();
+export const testImeLastRestoreAtPerfMs = new Map<string, number>();
 
 export type TestImeFlushWait = 'idle' | 'covered' | 'aborted';
 
 // The write that earned the window calls this, on every confirmed emulator restore — close-time,
 // cross-session, or startup-orphan recovery.
 export function registerTestImeRestore(serial: string): void {
-  testImeLastRestoreAtMs.set(
+  testImeLastRestoreAtPerfMs.set(
     serial,
-    Math.max(testImeLastRestoreAtMs.get(serial) ?? 0, performance.now()),
+    Math.max(testImeLastRestoreAtPerfMs.get(serial) ?? 0, performance.now()),
   );
 }
 
@@ -58,20 +62,20 @@ export async function awaitTestImeFlushWindow(
   signal?: AbortSignal,
 ): Promise<TestImeFlushWait> {
   if (signal?.aborted) return 'aborted';
-  const restoredAtMs = testImeLastRestoreAtMs.get(serial);
-  if (restoredAtMs === undefined) return 'idle';
-  const remainingMs = restoredAtMs + SETTINGS_PROVIDER_FLUSH_SETTLE_MS - performance.now();
+  const restoredAtPerfMs = testImeLastRestoreAtPerfMs.get(serial);
+  if (restoredAtPerfMs === undefined) return 'idle';
+  const remainingMs = restoredAtPerfMs + SETTINGS_PROVIDER_FLUSH_SETTLE_MS - performance.now();
   if (remainingMs <= 0) {
-    testImeLastRestoreAtMs.delete(serial);
+    testImeLastRestoreAtPerfMs.delete(serial);
     return 'covered';
   }
   await sleep(remainingMs, signal);
   if (signal?.aborted) return 'aborted';
-  // Retire only the timestamp this wait actually covered: a restore that landed mid-wait (the
+  // Retire only the mark this wait actually covered: a restore that landed mid-wait (the
   // unlocked shutdown-command path racing a close finalization) must keep its evidence for the
   // next kill-bound caller rather than have its younger window erased by this older wait.
-  if (testImeLastRestoreAtMs.get(serial) === restoredAtMs) {
-    testImeLastRestoreAtMs.delete(serial);
+  if (testImeLastRestoreAtPerfMs.get(serial) === restoredAtPerfMs) {
+    testImeLastRestoreAtPerfMs.delete(serial);
   }
   return 'covered';
 }
@@ -105,7 +109,7 @@ export function withAndroidTestImeRecoveryLock<T>(
  */
 export function resetAndroidTestImeActivationCacheForTests(): void {
   activeTestImeDevices.clear();
-  testImeLastRestoreAtMs.clear();
+  testImeLastRestoreAtPerfMs.clear();
 }
 
 /**

packages/platform-android/src/shutdown/runtime.test.ts

@@ -9,7 +9,7 @@ vi.mock('@agent-device/host-kit/retry', async (importOriginal) => ({
   sleep,
 }));
 
-import { testImeLastRestoreAtMs } from '../ime-state.ts';
+import { testImeLastRestoreAtPerfMs } from '../ime-state.ts';
 
 const run = vi.fn(async () => ({ stdout: '', stderr: '', exitCode: 0 }));
 const commands: DeviceShutdownRuntimeDependencies['commands'] = {
@@ -21,7 +21,7 @@ beforeEach(() => {
   run.mockReset();
   run.mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 });
   sleep.mockClear();
-  testImeLastRestoreAtMs.clear();
+  testImeLastRestoreAtPerfMs.clear();
 });
 
 test('an already-stopped emulator succeeds without adb', async () => {
@@ -60,7 +60,7 @@ test('only Android emulators are available', () => {
 // caller) inherits it without knowing about the test IME.
 test('a kill waits out a registered test-IME flush window before running adb emu kill', async () => {
   const device = androidDevice();
-  testImeLastRestoreAtMs.set(device.id, performance.now());
+  testImeLastRestoreAtPerfMs.set(device.id, performance.now());
 
   await expect(
     createAndroidShutdownRuntime({ commands }).shutdownTarget(device, signal()),
@@ -72,14 +72,14 @@ test('a kill waits out a registered test-IME flush window before running adb emu
   // gap. A regression sleeping a fixed unrelated amount would fail here.
   expect(sleep.mock.calls[0]?.[0]).toBeGreaterThanOrEqual(2_000);
   expect(run).toHaveBeenCalledTimes(1);
-  expect([...testImeLastRestoreAtMs.keys()]).toEqual([]);
+  expect([...testImeLastRestoreAtPerfMs.keys()]).toEqual([]);
 });
 
 test('a forward host wall-clock jump cannot shorten a registered flush window', async () => {
   // The window is timed on the process monotonic clock, so an NTP/VM-resume step of the wall
   // clock must leave the kill-side remaining wait at the full budget.
   const device = androidDevice();
-  testImeLastRestoreAtMs.set(device.id, performance.now());
+  testImeLastRestoreAtPerfMs.set(device.id, performance.now());
   const nowSpy = vi.spyOn(Date, 'now').mockReturnValue(Number.MAX_SAFE_INTEGER);
 
   try {
@@ -107,7 +107,9 @@ test('a kill skips the wait entirely when no flush window is open', async () =>
 
 test('a kill cancelled inside the flush window never reaches adb emu kill', async () => {
   const device = androidDevice();
-  testImeLastRestoreAtMs.set(device.id, performance.now());
+  // Known elapsed: the mark is 1000 ms old, so the derived remainder must be ~1500 — not the
+  // full budget, not a fixed constant. That makes both waits provably a function of the mark.
+  testImeLastRestoreAtPerfMs.set(device.id, performance.now() - 1_000);
   const controller = new AbortController();
   sleep.mockImplementationOnce((_ms, waitSignal) => {
     controller.abort();
@@ -119,8 +121,21 @@ test('a kill cancelled inside the flush window never reaches adb emu kill', asyn
   ).rejects.toBeDefined();
 
   expect(run).not.toHaveBeenCalled();
-  // The window stays registered so a retry still waits out the remainder.
-  expect([...testImeLastRestoreAtMs.keys()]).toEqual([device.id]);
+  const firstRemainingMs = sleep.mock.calls[0]?.[0] as number;
+  expect(firstRemainingMs).toBeGreaterThan(1_400);
+  expect(firstRemainingMs).toBeLessThanOrEqual(1_500);
+  // The window stays registered so a retry still waits out the remainder — and the retry
+  // re-derives the SAME remainder from the surviving mark: the monotonic-mark property the
+  // abort design rests on, pinned by number, not by shape.
+  expect([...testImeLastRestoreAtPerfMs.keys()]).toEqual([device.id]);
+
+  const retry = await createAndroidShutdownRuntime({ commands }).shutdownTarget(device, signal());
+
+  expect(retry).toEqual(success());
+  expect(sleep).toHaveBeenCalledTimes(2);
+  const secondRemainingMs = sleep.mock.calls[1]?.[0] as number;
+  expect(secondRemainingMs).toBeGreaterThan(1_400);
+  expect(secondRemainingMs).toBeLessThanOrEqual(firstRemainingMs);
 });
 
 function signal(): AbortSignal {