feat(settle): prototype an adaptive early exit behind an internal switch (off by default)
Summary
This is a prototype of an adaptive short confirmation for --settle, for review as is. It is off by default. It runs only when the daemon host environment sets AGENT_DEVICE_SETTLE_ADAPTIVE=1, which the daemon passes on as SettleParams.earlyExit: 'adaptive'. It adds no CLI flag and does not change the output shape. With the switch off, every path matches main; the loop refactor is behavior-neutral.
Flipping the default is not part of this PR. It needs:
- the ADR 0011
settleObservationguarantee; - its
interaction-guarantees.tsmatrix cell; - the
--settlehelp.
The rule (settle-adaptive-confirmation.ts):
- The first capture that differs from a fresh pre-action baseline gets one confirming capture 110 ms later.
- If that capture is equal and from the same producer/presented surface, settle.
- These conditions escalate to today's quiet window:
- the two captures disagree;
- a busy indicator is on screen (the classification from #4513, now shared in
kernel); - the presented surface changed;
- the 1.5 s broad-replacement floor applies;
- the capture holds the baseline beside a new screen (a transition union);
- the baseline was not captured by this action, and the daemon does not report the session observation current. Current means: the frame is active, its tree is the newest observation, and nothing outdated it (
wait text, Android freshness reads).
- If nothing differs from the baseline, the quiet window applies as today.
Deadlines, quality checks, private-AX recovery and diff output are unchanged.
The PR touches 20 files, including a test-only Settle lab fixture screen (agent-device-test-app://settle-lab).
Results
Each cell is N=15 (tab: 30), with 2.5 s post-checks (diff snapshot against the stored settled tree) and blocks rotated across arms.
- on/off: pass 2, built at
3e048a7f7c. - main: pass 1, built at
244d1ff683. - Wrong: settled, but the screen changed afterwards.
iOS (iPhone 17 Pro sim, snapshot -i frame, bridge producer, 300 ms window)
| scenario | wall p50/p95 ms on · off · main | settle wait p50 on · off | captures on · off | wrong on · off · main |
|---|---|---|---|---|
| counter | 806/3080 · 1002/2628 · 1122/3625 | 221 · 417 | 2 · 2 | 0 · 0 · 0 |
| fill | 2913/3959 · 3084/4176 · 3289/5403 | 327 · 505 | 2 · 2 | 1 · 1 · 0 |
| tab | 1128/1170 · 1359/1562 · 1378/1610 | 293 · 497 | 2 · 2 | 0 · 0 · 0 |
| push | 1804/2292 · 1903/3063 · 1901/2256 | 935 · 968 | 3 · 3 | 0 · 0 · 0 |
| back | 1844/1985 · 2013/2262 · 1997/2500 | 476 · 658 | 2 · 2 | 0 · 0 · 0 |
| open-automation | 1582/1817 · 1605/2165 · 1692/2699 | 927 · 927 | 3 · 3 | 2 · 2 · 0 |
| back-to-settings | 1621/3686 · 1797/4041 · 1957/4550 | 269 · 475 | 2 · 2 | 0 · 0 · 0 |
| sheet-present | 1203/1307 · 1220/1333 · 1298/1633 | 518 · 518 | 2 · 2 | 0 · 0 · 0 |
| sheet-dismiss | 2414/2591 · 2428/2502 · 2503/3016 | 1680 · 1697 | 5 · 5 | 0 · 0 · 0 |
| delay500 | 1187/1323 · 1354/1495 · 1407/1472 | 603 · 778 | 3 · 3 | 0 · 0 · 0 |
| delay800 | 997/1331 · 1048/1298 · 1004/1134 | 418 · 435 | 2 · 2 | 15 · 15 · 15 |
| overlay | 805/837 · 1071/1634 · 1036/1134 | 225 · 442 | 2 · 2 | 15 · 15 · 15 |
| stage-spinner | 997/1382 · 1391/2256 · 1000/2485 | 418 · 812 | 2 · 3 | 14 · 6 · 10 |
| stage-plain | 827/1105 · 1067/2375 · 1043/1485 | 238 · 434 | 2 · 2 | 15 · 10 · 10 |
| toast-nav | 814/1560 · 1052/2959 · 1066/3162 | 226 · 435 | 2 · 2 | 15 · 14 · 13 |
Android (API 37 AVD, full snapshot frame, helper, 500 ms window)
| scenario | wall p50/p95 ms on · off · main | settle wait p50 on · off | captures on · off | wrong on · off · main |
|---|---|---|---|---|
| counter | 542/1034 · 780/1124 · 901/1276 | 233 · 540 | 2 · 3 | 0 · 0 · 0 |
| fill | 694/1185 · 1044/2695 · 1249/1851 | 214 · 560 | 2 · 3 | 0 · 0 · 0 |
| tab | 1523/2239 · 1856/3021 · 1635/2473 | 972 · 1264 | 4 · 3 | 0 · 0 · 0 |
| push | 958/2972 · 1270/2412 · 1361/1956 | 678 · 1007 | 3 · 4 | 0 · 0 · 0 |
| back | 1005/1824 · 1392/2879 · 1381/1512 | 791 · 1175 | 3 · 4 | 0 · 0 · 0 |
| open-automation | 1024/2427 · 1414/1790 · 1474/1982 | 779 · 1155 | 3 · 4 | 0 · 0 · 0 |
| back-to-settings | 968/1689 · 1321/2020 · 1356/1735 | 743 · 1096 | 3 · 4 | 0 · 0 · 0 |
| sheet-present | 806/1112 · 1225/1449 · 1454/2124 | 566 · 971 | 3 · 4 | 0 · 0 · 0 |
| sheet-dismiss | 587/754 · 1003/1196 · 1131/1875 | 342 · 731 | 2 · 3 | 0 · 0 · 0 |
| delay500 | 1008/1248 · 804/1546 · 1344/1933 | 752 · 545 | 4 · 3 | 2 · 8 · 3 |
| delay800 | 775/959 · 777/1615 · 796/906 | 536 · 538 | 3 · 3 | 15 · 14 · 15 |
| overlay | 675/819 · 828/1650 · 1126/2180 | 321 · 561 | 2 · 3 | 15 · 12 · 10 |
| stage-spinner | 825/1600 · 853/1547 · 1486/1689 | 582 · 578 | 3 · 3 | 12 · 9 · 6 |
| stage-plain | 469/697 · 1059/1997 · 804/1657 | 228 · 570 | 2 · 3 | 15 · 8 · 11 |
| toast-nav | 687/719 · 810/1854 · 865/2076 | 456 · 554 | 3 · 3 | 15 · 8 · 10 |
Delayed effects with an immediate acknowledgement (re-measured at 7dad132c87 after review). The Settle lab now shows a "Run N" marker as soon as an action starts, so these cells measure "acknowledgement now, result later". In the tables above, the delay500/delay800 rows measured "no change, then a late change".
| platform | scenario | wall p50/p95 ms on · off | settle wait p50 on · off | wrong on · off |
|---|---|---|---|---|
| iOS | delay500 | 812/3506 · 1362/4003 | 230 · 784 | 15 · 0 |
| iOS | delay800 | 811/907 · 1001/1066 | 231 · 425 | 15 · 15 |
| Android | delay500 | 483/740 · 1504/1793 | 234 · 1266 | 15 · 2 |
| Android | delay800 | 472/711 · 1703/1794 | 228 · 1464 | 15 · 6 |
The early exit settles on the acknowledgement every time. Today's window still catches a 500 ms result on iOS, and most Android results.
Checkout flow (10 steps, 9 settled; N=15; p50/p95 total):
- iOS: on 25.6/29.1 s, off 27.5/36.2 s, main 27.5/32.4 s.
- Android: on 11.9/21.2 s, off 14.9/21.1 s, main 16.2/18.0 s.
Which escalations mattered:
- Transition union. Pass 1 (
210c5b1f6f) ran without it. There, iOS stack pushes settled mid-transition: 9/15 and 14/15 wrong, versus 0/15 for off. With it, both match off. - Frame currency. In pass 1, Android never armed: selector resolutions run in a different view than a full-snapshot frame.
- Presented surface and broad floor. These keep the sheet cases at today's latency.
- Busy indicator. It blocks the early exit but cannot lengthen today's window. The 600 ms spinner plateau beats 300/500 ms in every arm.
What the rule makes worse: an action that acknowledges immediately and finishes later (above) is always wrong with the switch on. Also, unmarked multi-stage effects go from often wrong to always wrong. These are the plain intermediate step, toast-then-navigate, and the fading overlay. Today's rule already misses them 8–15/15 times, as it does delay800.
Recommendation
Don't flip the default yet.
- For single-stage effects (in-place, fill, tab, push, back, sheet), the rule saves ~200 ms (iOS) and ~300–400 ms (Android) of settle wait. On those it adds no wrong settles.
- Both producers gain, so a per-producer default isn't justified.
- Next steps before a default:
- a busy-indicator hold (wait for it to leave);
- a run on real apps.
A default change would need these updates (none are in this PR):
- the ADR 0011
settleObservationguarantee; - the
interaction-guarantees.tsmatrix cell; - the
--settlehelp and docs; settle-observation.test.ts;- the TS/Swift parity table, if required.
Validation
- The touched suites pass. Each escalation was mutation-checked.
- Failing-first tests:
- the
@reffreshness test fails on9492f88; - the requested-window floor test (
quietMs: 2000) fails with thec423b99guard.
Both pass at the head.
- the
- Typecheck passes.
- Measured on the iPhone 17 Pro simulator and the API 37 AVD; 1-minute load averages ranged from 5 to 86.
- Caveats:
- Android
snapshot -ihides text, so Android uses full snapshots. - In the measured bundle, the overlay was laid out in flow; this is fixed in source.
- The freshness fixes after the runs (
9492f88, andobservationCurrentat421179e5d6) change only flows afterwait textor after a newer observation, which the benchmark never takes.
- Android
- CI at
8d80138216was green (18 checks). The unrelated wait-target dedupe moved to #4618. - Device smoke lanes run once the PR is ready for review.
🤖 Generated with Claude Code