things-api 0.19.3 → 0.20.0

package/dist/write/vectors/ui.js

@@ -35,37 +35,50 @@ import { createReachabilityCache, H_UI_SESSION_UNREACHABLE, probeSessionReachabi
 import { certificationOf } from "./ui-certification.js";
 import { chordCommand, driveHeadingChordReorder } from "./ui-chord.js";
 import { driveSidebarAreaReorder, jxaSidebarSnapshotScript } from "./ui-drag.js";
-import { AX_DIALOG_SHELL_SNIPPET, CENSUS_TIMEOUT_MS, censusUnverifiable, describeFocusOwner, describeUnprovenProbes, readUiState, SYNC_GATE_WARNING, THINGS_PROCESS, } from "./ui-state.js";
+import { AX_DIALOG_SHELL_SNIPPET, axFocusGuardPrelude, CENSUS_TIMEOUT_MS, censusUnverifiable, describeFocusOwner, describeUnprovenProbes, GUARD_REFUSED_TAG, parseGuardLog, readUiState, SYNC_GATE_WARNING, THINGS_PROCESS, } from "./ui-state.js";
 /** GUI driving can stall on an unanswered sheet; give each step headroom. */
 const STEP_TIMEOUT_MS = 15_000;
 /**
- * Poll interval while waiting for a dynamic element (sheet/popover). KEPT at 300ms
- * after the PERF2 audit: the control a mode switch reveals takes ~462ms to appear
- * on the golden (S5b, [docs/lab/perf2-step-latency.md]), which EXCEEDS this
- * interval — so a 300ms poll catches it on its second round; a finer interval
- * would only add osascript hops for a marginal detection gain (UIC6 confirmed).
- */
-const WAIT_POLL_MS = 300;
-/**
- * How long `resolveStepPath` polls a candidate-addressed control before failing
+ * How long a candidate-addressed control is polled for before the step fails
  * closed. The full-vocabulary dialog reveals a pop-up/field a beat AFTER the
  * frequency/Ends switch that precedes it (UIC6: ~250 ms), so the effective-form
- * resolution must poll, not snap once.
+ * resolution must poll, not snap once. Since DRVLAT1 (issue #633) that poll runs
+ * IN-SCRIPT, inside the hop that acts on the control ({@link axCandidatePrelude}),
+ * rather than as its own osascript round-trip per candidate per round.
  */
 const RESOLVE_CANDIDATE_TIMEOUT_MS = 5_000;
 /**
- * Settle after the reveal/activate preamble so the menu bar repopulates for the
- * newly-selected target before the canary reads it (UIC1: the Items ▸ Repeat
- * submenu appears only once a repeating item is selected, and the update is not
- * instantaneous). TRIMMED 1500 → 1000 by the PERF2 audit (S5a,
- * [docs/lab/perf2-step-latency.md]): on a warm running app under DEFAULT macOS
- * animations the menu repopulates in ~92ms median / 116ms max (N=10) — a ~13×
- * margin at 1500. Menu-bar repopulation is a LOCAL UI operation (not a DB-commit /
- * sync-bound one), so it does not scale with DB size the way the OK commit does;
- * 1000ms keeps ~8.6× the golden max as host headroom. Under-margining only ever
- * costs a fail-closed spurious drive refusal (the canary miss), never a bad write.
+ * In-script poll cadence for the element waits the drive folded into their own
+ * hops (DRVLAT1, issue #633). The JS-side poll it replaces was kept at a coarse
+ * 300ms deliberately — it paid a PROCESS SPAWN per round (PERF2 S5b), so a finer
+ * interval bought detection at the price of hops. An in-script poll pays one
+ * addressed `exists` per round, so it can be fine enough that a wait ends when
+ * the element lands rather than at the next 300ms boundary.
+ */
+const IN_SCRIPT_POLL_S = 0.05;
+/**
+ * How long the canary and the eligibility assertion poll for the menu bar to
+ * repopulate around the newly-selected target (UIC1: the Items ▸ Repeat submenu
+ * appears only once a matching item is selected, and the update is not
+ * instantaneous).
+ *
+ * This REPLACES the fixed post-preamble settle (DRVLAT1, issue #633). That settle
+ * was 1500ms, trimmed to 1000ms by PERF2 against a measured ~92ms median / 116ms
+ * max menu repopulation (S5a) — i.e. it spent ~900ms of every drive waiting out a
+ * margin, on every host, whether or not the menu was already there. The closed-loop
+ * form is strictly better on both axes: it proceeds the moment the menu answers
+ * (the common case, ~one poll), and it tolerates a host slower than any fixed
+ * settle would have covered. Under-margining still only ever costs a fail-closed
+ * refusal, never a bad write (determinism doctrine; BEEP1 shape-settle precedent).
+ */
+const MENU_SETTLE_TIMEOUT_MS = 4_000;
+/**
+ * Default window for a click's post-condition wait when the step names none.
+ * Every recipe that asserts one sets 5000 explicitly; this only keeps the
+ * in-script poll comfortably INSIDE the hop's own {@link STEP_TIMEOUT_MS}, which
+ * a 15s default would not (the poll would outlive its transport).
  */
-const SETTLE_AFTER_REVEAL_MS = 1000;
+const WAIT_ASSERT_TIMEOUT_MS = 5_000;
 /**
  * A shape-dependent step reached without the dialog having been measured — a
  * recipe bug (the `probe-dialog-shape` step is missing or ran after its
@@ -299,6 +312,82 @@ end fgAssertFront`;
 export function axResolveScript(path) {
     return `${SE} to return (exists (${path}))`;
 }
+/**
+ * The AppleScript variable a folded candidate resolution binds the live element
+ * to. Every addressed script takes its target as `(<path>)`, so handing it this
+ * name — with {@link axCandidatePrelude} in front — makes the resolution and the
+ * action ONE hop instead of two (DRVLAT1, issue #633).
+ */
+export const STEP_ELEMENT_REF = "fgStepEl";
+/**
+ * The message a folded candidate resolution raises when NONE of a step's expected
+ * element shapes appeared. Byte-identical to the driver's own wording for the
+ * separate-hop resolution it replaces, so a report reads the same either way.
+ */
+export const CANDIDATES_MISSED = "none of its expected element shapes resolved (neither the attached sheet nor the " +
+    "detached repeat editor window)";
+/**
+ * IN-SCRIPT CANDIDATE RESOLUTION (DRVLAT1, issue #633).
+ *
+ * A candidate-addressed step used to dispatch one `resolve` hop PER CANDIDATE PER
+ * POLL ROUND before the hop that acted on whichever answered — a process spawn
+ * each, on top of a 300ms JS-side poll floor. This prelude does the same work in
+ * the acting hop's own process: it polls the candidates in the SAME priority
+ * order, binds the first that exists to {@link STEP_ELEMENT_REF}, and fails closed
+ * with {@link CANDIDATES_MISSED} when the window elapses with none of them there.
+ *
+ * Collapsing it is also strictly better against TOCTOU: the element the script
+ * acts on is the one it just proved exists, with nothing dispatched in between.
+ */
+export function axCandidatePrelude(paths, timeoutMs = RESOLVE_CANDIDATE_TIMEOUT_MS) {
+    const probes = paths
+        .map((p) => `    try
+      if (exists (${p})) then set ${STEP_ELEMENT_REF} to (${p})
+    end try
+    if ${STEP_ELEMENT_REF} is not missing value then exit repeat`)
+        .join("\n");
+    return `set ${STEP_ELEMENT_REF} to missing value
+set fgT0 to (current date)
+${SE}
+  repeat
+${probes}
+    if ((current date) - fgT0) is greater than or equal to ${pollSeconds(timeoutMs)} then exit repeat
+    delay ${IN_SCRIPT_POLL_S}
+  end repeat
+end tell
+if ${STEP_ELEMENT_REF} is missing value then error "${escapeAppleScript(CANDIDATES_MISSED)}"`;
+}
+/**
+ * wait: poll for ANY of the awaited element shapes to appear, IN-SCRIPT (DRVLAT1).
+ * One hop for the whole wait instead of one per candidate per round — which is
+ * what a slow host paid most: the dialog the drive is waiting for is exactly the
+ * thing that is slow when the app is busy. Returns "true", or "false" when the
+ * window elapses with none of them present (the driver's abort path is unchanged).
+ */
+export function axWaitAnyScript(paths, timeoutMs) {
+    const probes = paths
+        .map((p) => `    try
+      if (exists (${p})) then return "true"
+    end try`)
+        .join("\n");
+    return `set fgT0 to (current date)
+${SE}
+  repeat
+${probes}
+    if ((current date) - fgT0) is greater than or equal to ${pollSeconds(timeoutMs)} then return "false"
+    delay ${IN_SCRIPT_POLL_S}
+  end repeat
+end tell`;
+}
+/**
+ * A poll window in whole seconds, as the in-script `current date` deadline reads
+ * it (AppleScript dates carry second granularity). Never below 1: a sub-second
+ * window would make a loop that checks its deadline after the FIRST probe into a
+ * single-shot check, which is the race these loops exist to close.
+ */
+function pollSeconds(timeoutMs) {
+    return Math.max(1, Math.round(timeoutMs / 1000));
+}
 /** press: AXPress the element. */
 export function axPressScript(path) {
     return `${SE} to click (${path})`;
@@ -821,12 +910,20 @@ export function axSelectPopupScript(path, value) {
  */
 export function axSelectPopupCandidatesScript(path, values) {
     const list = values.map((v) => `"${escapeAppleScript(v)}"`).join(", ");
+    // The menu is WAITED FOR, not slept on (DRVLAT1, issue #633): the old loop paid
+    // a flat 0.3s after every click before it would look again, so the common case —
+    // one click, menu up in well under that — spent the remainder of the settle
+    // doing nothing. The click cadence is unchanged (one click per round, never a
+    // second click into a menu that is opening — BEEP1); only the looking is finer.
     return `${SE}
   set pu to (${path})
   repeat 20 times
     if (exists menu 1 of pu) then exit repeat
     click pu
-    delay 0.3
+    repeat 6 times
+      if (exists menu 1 of pu) then exit repeat
+      delay ${IN_SCRIPT_POLL_S}
+    end repeat
   end repeat
   repeat with candidate in {${list}}
     if (exists menu item candidate of menu 1 of pu) then
@@ -1257,26 +1354,37 @@ return "NOMATCH"`;
  * naming expected vs observed. Pure System Events + Things scripting, background-
  * capable. One stable command shape per primitive.
  */
-export function axAssertEligibleScript(targetUuid, menuItemPath) {
+export function axAssertEligibleScript(targetUuid, menuItemPath, settleMs = MENU_SETTLE_TIMEOUT_MS) {
     const u = escapeAppleScript(targetUuid);
-    return `set selIds to {}
-tell application "Things3"
-  try
-    set selIds to id of selected to dos
-  end try
-end tell
-if (count of selIds) is 0 then return "NOTSEL no to-do is selected after the reveal (expected ${u}) — the show URL navigated without selecting an eligible row"
-if (count of selIds) is greater than 1 then return "NOTSEL " & (count of selIds) & " to-dos are selected, expected exactly the target ${u}"
-set theId to (item 1 of selIds) as text
-if theId is not "${u}" then return "WRONGSEL the selected to-do is " & theId & ", expected the target ${u}"
-set repEnabled to false
-tell application "System Events" to tell process "Things3"
-  try
-    set repEnabled to enabled of ${menuItemPath}
-  end try
-end tell
-if repEnabled is false then return "DISABLED the target ${u} is selected but its Repeat menu item is disabled (not an eligible row for this action)"
-return "OK"`;
+    return `set t0 to (current date)
+set verdict to my aeCheck()
+repeat until verdict is "OK"
+  if ((current date) - t0) is greater than or equal to ${pollSeconds(settleMs)} then exit repeat
+  delay ${IN_SCRIPT_POLL_S}
+  set verdict to my aeCheck()
+end repeat
+return verdict
+
+on aeCheck()
+  set selIds to {}
+  tell application "Things3"
+    try
+      set selIds to id of selected to dos
+    end try
+  end tell
+  if (count of selIds) is 0 then return "NOTSEL no to-do is selected after the reveal (expected ${u}) — the show URL navigated without selecting an eligible row"
+  if (count of selIds) is greater than 1 then return "NOTSEL " & (count of selIds) & " to-dos are selected, expected exactly the target ${u}"
+  set theId to (item 1 of selIds) as text
+  if theId is not "${u}" then return "WRONGSEL the selected to-do is " & theId & ", expected the target ${u}"
+  set repEnabled to false
+  tell application "System Events" to tell process "Things3"
+    try
+      set repEnabled to enabled of ${menuItemPath}
+    end try
+  end tell
+  if repEnabled is false then return "DISABLED the target ${u} is selected but its Repeat menu item is disabled (not an eligible row for this action)"
+  return "OK"
+end aeCheck`;
 }
 /** activate: foreground Things (the fallback preamble step). */
 export function axActivateScript() {
@@ -1613,7 +1721,7 @@ async function clickCancel(run) {
     const center = parseFrameCenter(frameRes.stdout);
     if (center === null)
         return false;
-    const res = await run(clickPointCommand(center.x, center.y, "click the open dialog's Cancel button"), STEP_TIMEOUT_MS);
+    const res = await run(uiClickPointCommand(center.x, center.y, "click the open dialog's Cancel button"), STEP_TIMEOUT_MS);
     return res.ok;
 }
 /**
@@ -1872,7 +1980,12 @@ $.CGEventPost($.kCGHIDEventTap, mev(1)); sleep(15);
 $.CGEventPost($.kCGHIDEventTap, mev(2));`;
 }
 /** The command that posts an AX-resolved mouse click (one stable JXA shape). */
-function clickPointCommand(x, y, label) {
+/**
+ * A synthesized HID click at a screen point. Exported (issue #640) so the rescue
+ * path's Cancel fallback and the drive's own click are literally the same shape
+ * — a second construction site is a second place for the event sequence to drift.
+ */
+export function uiClickPointCommand(x, y, label) {
     return { primitive: "click-point", label, lang: "javascript", script: jxaClickScript(x, y) };
 }
 /**
@@ -2060,13 +2173,28 @@ async function defaultRun(command, timeoutMs) {
 }
 /**
  * Read the live window/focus census through the shipped dispatch seam — the
- * transport behind the `ui-state` diagnostic (src/ui-state.ts) and, in tests,
+ * transport behind the window-state diagnostic (src/ui-state.ts) and, in tests,
  * behind any injected runner. READ-ONLY: the census clicks nothing, types
  * nothing, and changes no state; see src/write/vectors/ui-state.ts.
  */
 export function readLiveUiState(run = defaultRun) {
     return readUiState(run, CENSUS_TIMEOUT_MS);
 }
+/**
+ * The production dispatch seam itself, exported (issue #640).
+ *
+ * The drive owns its own runner and always will. But `things rescue` presses a
+ * button on a dialog no drive opened, so it needs the SAME transport — the
+ * deputy routing, the reveal/osascript split, the timeout handling — without
+ * borrowing the drive's recipe machinery. Re-declaring a second dispatcher would
+ * mean a second place for the deputy contract to drift, which is the one thing
+ * this seam exists to prevent.
+ *
+ * Nothing else changes: this is `defaultRun` under a name a caller outside the
+ * vector can read, and every injected-runner test seam still works exactly as
+ * before.
+ */
+export const defaultUiRunner = defaultRun;
 /**
  * Wrap the dispatch seam so every osascript hop is recorded. The last-dispatched
  * step is noted on the in-flight-write marker (so a SIGTERM/SIGINT can name it,
@@ -2186,24 +2314,32 @@ export function judgeFocusGuard(state, expectedSheet, label) {
  * state, taken immediately before the hop, and the in-script assertions close
  * the remaining milliseconds (UI-automation determinism doctrine; the #595
  * pre-commit audit and BEEP1 shape-settle are the same pattern).
+ *
+ * FOLDED for keystroke-class hops (DRVLAT1, issue #633). Those hops are
+ * AppleScript, so the census can be — and now is — the PRELUDE OF THE VERY SCRIPT
+ * THAT TYPES ({@link axFocusGuardPrelude}) rather than a hop of its own. Two
+ * things improve at once: the drive stops paying a process spawn per typed
+ * control, and the TOCTOU window between "the census approved this" and "the
+ * keystroke went out" closes to nothing — no dispatch happens in between, because
+ * there is nothing in between. The judgement is still made BEFORE the keystroke
+ * (in-script, fail-closed) and the sentence a caller reads is still built HERE by
+ * {@link judgeFocusGuard}, from the census that same hop logged, so there remains
+ * exactly one wording of every refusal.
+ *
+ * POINTER-class hops keep the separate census: they dispatch JXA, which cannot
+ * carry an AppleScript prelude.
  */
 function guardedRun(inner, latch) {
     return async (command, timeoutMs) => {
-        if (!KEYSTROKE_CLASS.has(command.primitive) && !POINTER_CLASS.has(command.primitive)) {
+        const keystroke = KEYSTROKE_CLASS.has(command.primitive);
+        if (!keystroke && !POINTER_CLASS.has(command.primitive)) {
             return inner(command, timeoutMs);
         }
-        const state = await readUiState(inner, CENSUS_TIMEOUT_MS);
-        // An inspection that would not answer poisons every later inspection's
-        // credibility, so the cleanup ladder is told once and never asks again
-        // (issue #629).
-        if (state === null || censusUnverifiable(state))
-            latch.inspectionStalled = true;
         // The dialog invariant applies to keystroke-class hops only: a pointer hop
         // is aimed at a frame it resolved a moment ago and fails closed on its own
         // if that frame moved.
-        const expected = KEYSTROKE_CLASS.has(command.primitive) ? latch.sheet : null;
-        const guardRefusal = judgeFocusGuard(state, expected, command.label);
-        if (guardRefusal !== null) {
+        const expected = keystroke ? latch.sheet : null;
+        const refuse = (state, why) => {
             trace(() => ({
                 phase: "focus-guard",
                 event: "refused",
@@ -2214,10 +2350,41 @@ function guardedRun(inner, latch) {
                 inspectable: state?.inspectable ?? false,
                 stalled: state?.stalledProbes ?? null,
             }));
-            return { ok: false, stdout: "", stderr: guardRefusal };
+            return { ok: false, stdout: "", stderr: why };
+        };
+        // An inspection that would not answer poisons every later inspection's
+        // credibility, so the cleanup ladder is told once and never asks again
+        // (issue #629).
+        const noteStall = (state) => {
+            if (state === null || censusUnverifiable(state))
+                latch.inspectionStalled = true;
+        };
+        // Latched only on a census that APPROVED the hop — a dialog seen while
+        // refusing is, by construction, not the one this drive is driving.
+        const latchSheet = (state) => {
+            if (state !== null && state.sheetOpen && latch.sheet === null)
+                latch.sheet = state.sheetKind;
+        };
+        if (keystroke && command.lang !== "javascript" && typeof command.script === "string") {
+            const res = await inner({ ...command, script: `${axFocusGuardPrelude(expected)}\n${command.script}` }, timeoutMs);
+            const { state, stderr } = parseGuardLog(res.stderr);
+            noteStall(state);
+            if (!res.ok && stderr.includes(GUARD_REFUSED_TAG)) {
+                // The script refused. Re-judge the census it logged for the sentence; a
+                // census too damaged to re-judge still refuses — the hop already did.
+                return refuse(state, judgeFocusGuard(state, expected, command.label) ??
+                    `refused to run "${command.label}": the window and focus state could not be read, so ` +
+                        "there is no proof the input would reach Things — nothing was sent");
+            }
+            latchSheet(state);
+            return { ...res, stderr };
         }
-        if (state !== null && state.sheetOpen && latch.sheet === null)
-            latch.sheet = state.sheetKind;
+        const state = await readUiState(inner, CENSUS_TIMEOUT_MS);
+        noteStall(state);
+        const guardRefusal = judgeFocusGuard(state, expected, command.label);
+        if (guardRefusal !== null)
+            return refuse(state, guardRefusal);
+        latchSheet(state);
         return inner(command, timeoutMs);
     };
 }
@@ -2295,40 +2462,43 @@ function canaryPaths(recipe) {
     }
     return out;
 }
-/**
- * Resolve a step's effective element path. A `pathCandidates` step dispatches
- * against the FIRST candidate that exists (the dialog-form disjunction — attached
- * sheet vs detached AXUnknown window, UIC4-a). The candidates are POLLED over a
- * bounded window because the full-vocabulary controls are REVEALED by the
- * preceding step: switching the frequency pop-up to weekly/monthly/yearly (or
- * ticking Ends=after) re-lays-out the cadence group, and the new pop-up/field
- * lands ~250 ms later (UIC6). A single immediate exists-check races that render
- * and would spuriously fail closed; polling matches the `dynamic` nature these
- * steps already declare. Returns null when none resolve within the window.
- */
-async function resolveStepPath(step, run) {
-    if (step.pathCandidates === undefined)
-        return step.path ?? null;
-    const candidates = step.pathCandidates;
-    const deadline = Date.now() + (step.timeoutMs ?? RESOLVE_CANDIDATE_TIMEOUT_MS);
-    for (;;) {
-        for (const candidate of candidates) {
-            // candidates are tried in priority order; the first hit wins, so a race would blur which form matched
-            const res = await run({ primitive: "resolve", label: step.label, script: axResolveScript(candidate) }, STEP_TIMEOUT_MS);
-            if (res.ok && res.stdout.trim() === "true")
-                return candidate;
-        }
-        if (Date.now() >= deadline)
-            return null;
-        // the revealed control lands a beat after the mode switch; poll until it does
-        await new Promise((r) => setTimeout(r, WAIT_POLL_MS));
-    }
-}
 function refusal(detail) {
     return { exitCode: 1, stdout: "", stderr: detail };
 }
-/** Compile one recipe step into its primitive command (no dispatch). */
+/**
+ * Compile one recipe step into its primitive command (no dispatch).
+ *
+ * A CANDIDATE-ADDRESSED step compiles to ONE script that resolves its own element
+ * and then acts on it (DRVLAT1, issue #633): the addressed body is generated
+ * against {@link STEP_ELEMENT_REF} and {@link axCandidatePrelude} is prepended, so
+ * the resolution that used to be a separate `resolve` hop (or several) now rides
+ * the acting hop. Steps whose script is JXA, or that resolve their own target,
+ * are unaffected.
+ */
 export function commandForStep(step, targetUuid) {
+    if (step.primitive === "wait") {
+        // The whole wait is ONE hop: the candidates are polled in-script until one of
+        // them exists or the step's own window elapses (DRVLAT1).
+        const paths = step.pathCandidates ?? [step.path ?? ""];
+        return {
+            primitive: "wait",
+            label: step.label,
+            script: axWaitAnyScript(paths, step.timeoutMs ?? STEP_TIMEOUT_MS),
+        };
+    }
+    if (step.pathCandidates !== undefined && step.path === undefined) {
+        const candidates = step.pathCandidates;
+        const inner = commandForStep({ ...step, path: STEP_ELEMENT_REF }, targetUuid);
+        // Only an AppleScript body can take the AppleScript prelude; a JXA step
+        // (set-datetime, the pointer primitives) resolves its own target anyway.
+        if (inner.lang === "javascript" || typeof inner.script !== "string" || inner.script === "") {
+            return inner;
+        }
+        return {
+            ...inner,
+            script: `${axCandidatePrelude(candidates, RESOLVE_CANDIDATE_TIMEOUT_MS)}\n${inner.script}`,
+        };
+    }
     switch (step.primitive) {
         case "reveal":
             return { primitive: "reveal", label: step.label, url: revealUrl(step.value ?? targetUuid) };
@@ -2418,8 +2588,6 @@ export function commandForStep(step, targetUuid) {
                 // shape-selected group pop-up index of the first weekday row (RDLG2).
                 script: axConvergeWeekdaysScript(step.path ?? "", weekdayBaseOf(step.value ?? ""), weekdayTitlesOf(step.value ?? "")),
             };
-        case "wait":
-            return { primitive: "wait", label: step.label, script: axResolveScript(step.path ?? "") };
         case "select-row":
             return {
                 primitive: "select-row",
@@ -2524,7 +2692,7 @@ async function driveClickElement(step, run) {
                     "or the app is not in the expected state; no click was sent",
         };
     }
-    const clickRes = await run(clickPointCommand(center.x, center.y, step.label), STEP_TIMEOUT_MS);
+    const clickRes = await run(uiClickPointCommand(center.x, center.y, step.label), STEP_TIMEOUT_MS);
     if (!clickRes.ok) {
         return {
             ok: false,
@@ -2535,12 +2703,13 @@ async function driveClickElement(step, run) {
         };
     }
     if (step.assertPath !== undefined) {
-        const ok = await waitForElement({
+        // one hop, polled in-script (DRVLAT1)
+        const res = await run({
             primitive: "wait",
             label: step.assertLabel ?? step.label,
-            script: axResolveScript(step.assertPath),
-        }, step.assertTimeoutMs ?? STEP_TIMEOUT_MS, run);
-        if (!ok) {
+            script: axWaitAnyScript([step.assertPath], step.assertTimeoutMs ?? WAIT_ASSERT_TIMEOUT_MS),
+        }, STEP_TIMEOUT_MS);
+        if (!(res.ok && res.stdout.trim() === "true")) {
             return {
                 ok: false,
                 why: `${step.assertLabel ?? "the expected element"} did not appear after the click`,
@@ -2705,6 +2874,7 @@ async function drive(recipe, rawRun, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS,
             exitCode: 1,
             stdout: `ui drive watchdog stopped after ${done.length} step(s): ${done.join(" → ") || "nothing"}`,
             stderr: `ui drive exceeded its ${Math.round(budgetMs / 1000)}s budget at "${lastStep}"`,
+            steps: [...done],
             timedOut: true,
             watchdog: {
                 budgetMs,
@@ -2738,7 +2908,11 @@ async function drive(recipe, rawRun, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS,
         // reachable to be driven — which is not the app accepting a command and
         // changing nothing, and must not be reported as that.
         const cause = clear?.state === "cleared-blind" ? "unreachable" : stepTimedOut ? "unresponsive" : null;
-        const res = refusal(base + cleanup);
+        // The step list rides EVERY partial exit: a failure always carries the
+        // play-by-play, which is what made the field bug reports rich (#632). The
+        // step that stopped the drive is named as the last entry so the list reads
+        // as the whole attempt, not only the part that worked.
+        const res = { ...refusal(base + cleanup), steps: [...done, `${failed} — FAILED: ${why}`] };
         if (cause === null)
             return res;
         return {
@@ -2772,9 +2946,9 @@ async function drive(recipe, rawRun, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS,
         done.push(step.label);
         idx += 1;
     }
-    // Let the selection settle so the menu bar repopulates before the canary reads it.
-    if (idx > 0)
-        await new Promise((r) => setTimeout(r, SETTLE_AFTER_REVEAL_MS));
+    // The menu bar repopulates around the new selection a beat after the preamble
+    // (UIC1). That beat is WAITED OUT IN THE CANARY below, which polls each element
+    // it must resolve — no fixed settle stands here any more (DRVLAT1, issue #633).
     // 0½. Session-reachability GATE for dialog-class ops (SESSGATE, #480). A recipe
     //     that opens a sheet on the main window needs that window AX-reachable on
     //     the current Space. Probed AFTER the preamble (which surfaces a window in a
@@ -2816,7 +2990,13 @@ async function drive(recipe, rawRun, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS,
     //    pressed. (This is also the localization check: English titles must resolve.)
     for (const { path, label } of canaryPaths(recipe)) {
         // the canary resolves elements one at a time; a single miss aborts before anything is pressed, so parallelizing would waste work and blur which element failed
-        const res = await run({ primitive: "resolve", label, script: axResolveScript(path) }, STEP_TIMEOUT_MS);
+        // POLLED, not snapped: this is where the drive waits out the menu-bar
+        // repopulation the preamble triggered (DRVLAT1 — it replaces the fixed settle).
+        const res = await run({
+            primitive: "resolve",
+            label,
+            script: axWaitAnyScript([path], MENU_SETTLE_TIMEOUT_MS),
+        }, STEP_TIMEOUT_MS);
         if (!res.ok || res.stdout.trim() !== "true") {
             // (e) A leftover modal sheet/popover from an earlier aborted drive disables
             // the menu bar, so the Items ▸ Repeat path cannot resolve. Detect that
@@ -2877,9 +3057,11 @@ async function drive(recipe, rawRun, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS,
             return watchdogResult(step.label);
         if (step.primitive === "wait") {
             // A candidate-addressed wait polls for ANY of its shapes to appear (the
-            // dialog opening as an attached sheet OR a detached AXUnknown window).
+            // dialog opening as an attached sheet OR a detached AXUnknown window) — the
+            // whole poll inside ONE hop (DRVLAT1).
             // steps are strictly sequential: this wait must resolve before the step that acts on the awaited element runs
-            const ok = await waitForAnyElement(step.pathCandidates ?? [step.path ?? ""], step.label, step.timeoutMs ?? STEP_TIMEOUT_MS, run);
+            const res = await run(commandForStep(step, recipe.targetUuid), STEP_TIMEOUT_MS);
+            const ok = res.ok && res.stdout.trim() === "true";
             if (!ok) {
                 // the abort keystroke must land (and be verified) before returning the partial-state report
                 const clear = await clearNow();
@@ -2917,19 +3099,11 @@ async function drive(recipe, rawRun, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS,
             done.push(`${step.label} (${outcome.detail})`);
             continue;
         }
-        // Resolve a candidate-addressed step's effective element before dispatch
-        // (the sheet-vs-detached-window disjunction). A miss fails closed.
-        if (step.pathCandidates !== undefined) {
-            // the effective form must be resolved before this step can act on it
-            const effective = await resolveStepPath(step, run);
-            if (effective === null) {
-                // dismiss whatever opened (and verify) before reporting
-                const clear = await clearNow();
-                return partial(step.label, "none of its expected element shapes resolved (neither the attached sheet nor the " +
-                    "detached repeat editor window)", clear);
-            }
-            step = { ...step, path: effective };
-        }
+        // A candidate-addressed step resolves its effective element (the
+        // sheet-vs-detached-window disjunction) INSIDE its own script now — see
+        // commandForStep / axCandidatePrelude. A miss raises CANDIDATES_MISSED there
+        // and lands on this step's ordinary failure path, with the same wording and
+        // the same clean abort it had when the resolution was its own hop (DRVLAT1).
         const command = commandForStep(step, recipe.targetUuid);
         if (step.primitive === "probe-dialog-shape") {
             // MEASURE the dialog (RDLG2) before any shape-dependent control is touched.
@@ -3045,39 +3219,12 @@ async function drive(recipe, rawRun, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS,
         exitCode: 0,
         stdout: `${relocationNote}drove ${done.length} step(s): ${done.join(" → ")}`,
         stderr: "",
+        // The same play-by-play as a LIST (#632). `stdout` keeps the prose form the
+        // trace and the transport-failure paths already read; `steps` is what the
+        // change-history record stores and `--verbose` renders.
+        steps: relocationNote === "" ? [...done] : [relocationNote.trim(), ...done],
     };
 }
-async function waitForElement(command, timeoutMs, run) {
-    const deadline = Date.now() + timeoutMs;
-    for (;;) {
-        // polling the same element until it appears is inherently sequential
-        const res = await run(command, STEP_TIMEOUT_MS);
-        if (res.ok && res.stdout.trim() === "true")
-            return true;
-        if (Date.now() >= deadline)
-            return false;
-        // inter-poll delay between sequential existence checks
-        await new Promise((r) => setTimeout(r, WAIT_POLL_MS));
-    }
-}
-/** Poll until ANY of the candidate element shapes exists (the sheet-vs-detached-window disjunction). */
-async function waitForAnyElement(paths, label, timeoutMs, run) {
-    const deadline = Date.now() + timeoutMs;
-    for (;;) {
-        for (const path of paths) {
-            // Emitted as the `wait` primitive (not `resolve`) so the command stream a
-            // caller observes is unchanged from the single-path waitForElement.
-            // candidates checked in priority order; the first present shape ends the wait
-            const res = await run({ primitive: "wait", label, script: axResolveScript(path) }, STEP_TIMEOUT_MS);
-            if (res.ok && res.stdout.trim() === "true")
-                return true;
-        }
-        if (Date.now() >= deadline)
-            return false;
-        // inter-poll delay between sequential existence checks
-        await new Promise((r) => setTimeout(r, WAIT_POLL_MS));
-    }
-}
 function enabledMatrix() {
     const matrix = {};
     for (const op of UI_DRIVE_OPS) {