things-api 0.19.2 → 0.19.4

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, describeFocusOwner, 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() {
@@ -1483,6 +1591,25 @@ ${AX_DIALOG_SHELL_SNIPPET}
   return "OK"
 end tell`;
 }
+/**
+ * The Cancel button's on-screen FRAME, resolved through the same addressed
+ * dialog-shell path the AXPress dismissal uses (issue #629). Feeds the pointer
+ * fallback: if `AXPress` on the button reports success and the dialog is still
+ * standing, a real click at the button's own AX-resolved centre is the next
+ * thing to try before discarding the window wholesale. The frame comes from the
+ * tree, never from a remembered coordinate, so a moved dialog fails closed.
+ */
+export function axCancelFrameScript() {
+    return `${SE}
+${AX_DIALOG_SHELL_SNIPPET}
+  if shellRef is missing value then error "no dialog is open"
+  if not (exists button "Cancel" of shellRef) then error "the open dialog has no Cancel button"
+  set _b to button "Cancel" of shellRef
+  set _p to position of _b
+  set _s to size of _b
+  return ((item 1 of _p) as text) & " " & ((item 2 of _p) as text) & " " & ((item 1 of _s) as text) & " " & ((item 2 of _s) as text)
+end tell`;
+}
 /**
  * The PROVEN app-level clearance / relocation maneuver (SESSGATE, #480, live-host
  * recovery): close the front Things window — which takes an attached modal sheet
@@ -1570,6 +1697,67 @@ async function pressCancel(run) {
     }, STEP_TIMEOUT_MS);
     return res.ok && res.stdout.trim() === "OK";
 }
+/**
+ * The pointer fallback for the Cancel rung (issue #629): a real click at the
+ * button's own AX-resolved centre, for the case where `AXPress` reports success
+ * and the dialog is demonstrably still standing. Needs Things frontmost — the
+ * HID tap posts at the foreground surface (NATIVE1-e) — so it activates first,
+ * and re-reads the frame AFTERWARDS, because bringing Things forward can
+ * re-attach a detached editor as a sheet and move the button.
+ */
+async function clickCancel(run) {
+    await run({
+        primitive: "activate",
+        label: "bring Things forward to click its dialog's Cancel button",
+        script: axActivateScript(),
+    }, STEP_TIMEOUT_MS);
+    const frameRes = await run({
+        primitive: "resolve-frame",
+        label: "locate the open dialog's Cancel button",
+        script: axCancelFrameScript(),
+    }, STEP_TIMEOUT_MS);
+    if (!frameRes.ok)
+        return false;
+    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);
+    return res.ok;
+}
+/**
+ * The dismissal that needs NO working inspection (issue #629): press the
+ * dialog's own Cancel button, PROVE the dialog is gone with one addressed
+ * existence read, and fall through to a real click at the button's frame if the
+ * press reported success while the dialog stayed up.
+ *
+ * This is the rung the field incident needed and did not have. Its cleanup
+ * re-ran the census that had just stalled, learned nothing three times over,
+ * and ended in the AX-blind close+reopen — which left the sheet standing, and
+ * with it the app-wide scripting freeze that stopped the composite trashing its
+ * own disposable copy (MODALX1 §2.1) and the Things Cloud sync gate.
+ *
+ * Everything here is addressed inside `process "Things3"`: {@link
+ * axCancelDialogScript} and {@link axSheetOpenScript} are the same shape as the
+ * drive steps that kept working while the census did not.
+ */
+async function semanticCancel(run, expected, owner) {
+    const kind = expected === null ? {} : { sheetKind: expected };
+    // A stack unwinds LIFO (MODALX1 §6), so press-and-verify in a loop rather
+    // than pressing once and assuming.
+    for (let i = 0; i < MAX_DISMISS_ROUNDS; i += 1) {
+        if (!(await pressCancel(run)))
+            break;
+        if (!(await sheetStillOpen(run))) {
+            return { state: "dismissed", how: "cancel-button", ...kind, ...owner, unverified: true };
+        }
+    }
+    if (await clickCancel(run)) {
+        if (!(await sheetStillOpen(run))) {
+            return { state: "dismissed", how: "cancel-button", ...kind, ...owner, unverified: true };
+        }
+    }
+    return closeReopenRung(run, expected, owner, false, true);
+}
 /**
  * Clear a half-open dialog a failed drive left behind — AUDITED at every rung
  * (issue #620; supersedes the unconditional Escape, which was measured firing
@@ -1594,8 +1782,15 @@ async function pressCancel(run) {
  * `expected` is the dialog kind this drive was observed driving; see
  * {@link oursToDismiss}.
  */
-async function clearDialog(run, expected = null) {
-    const census = await readUiState(run, STEP_TIMEOUT_MS);
+async function clearDialog(run, expected = null, inspectionStalled = false) {
+    // #629: the inspection already refused to answer once. Asking it again buys
+    // nothing and costs the caller another deadline — go straight to the rung
+    // that needs no inspection and proves itself with one addressed read.
+    if (inspectionStalled)
+        return semanticCancel(run, expected, {});
+    const census = await readUiState(run, CENSUS_TIMEOUT_MS);
+    if (censusUnverifiable(census))
+        return semanticCancel(run, expected, {});
     const owner = census !== null && !census.thingsFrontmost ? { focusOwner: describeFocusOwner(census) } : {};
     const readable = census !== null && census.inspectable;
     // 0. A clean, readable "no dialog" — but only trustworthy on a session whose
@@ -1623,7 +1818,7 @@ async function clearDialog(run, expected = null) {
         for (let i = 0; i < MAX_DISMISS_ROUNDS; i += 1) {
             if (!(await pressCancel(run)))
                 break;
-            const after = await readUiState(run, STEP_TIMEOUT_MS);
+            const after = await readUiState(run, CENSUS_TIMEOUT_MS);
             if (after === null || !after.inspectable)
                 break;
             if (!after.sheetOpen)
@@ -1642,7 +1837,7 @@ async function clearDialog(run, expected = null) {
             label: "bring Things forward to dismiss its dialog",
             script: axActivateScript(),
         }, STEP_TIMEOUT_MS);
-        const reaudit = await readUiState(run, STEP_TIMEOUT_MS);
+        const reaudit = await readUiState(run, CENSUS_TIMEOUT_MS);
         if (reaudit !== null && reaudit.inspectable) {
             if (!reaudit.sheetOpen)
                 return { state: "dismissed", how: "cancel-button", ...kind, ...owner };
@@ -1654,7 +1849,7 @@ async function clearDialog(run, expected = null) {
     }
     if (front) {
         await run({ primitive: "key", label: "abort (Escape)", script: axAbortScript() }, STEP_TIMEOUT_MS);
-        const after = await readUiState(run, STEP_TIMEOUT_MS);
+        const after = await readUiState(run, CENSUS_TIMEOUT_MS);
         if (after !== null && after.inspectable && !after.sheetOpen) {
             return { state: "dismissed", how: "escape", ...kind, ...owner };
         }
@@ -1668,7 +1863,13 @@ async function clearDialog(run, expected = null) {
  * `blind` says the session itself is AX-blind, in which case NOTHING the census
  * reports afterwards is evidence — the outcome is honestly unconfirmed.
  */
-async function closeReopenRung(run, expected, owner, blind = false) {
+async function closeReopenRung(run, expected, owner, blind = false, 
+/**
+ * #629: the window-state inspection is not answering, so the outcome is
+ * decided by the ADDRESSED sheet-open read instead of a fresh census. The
+ * verdict is still proven — just proven by a narrower question.
+ */
+inspectionStalled = false) {
     await run({
         primitive: "resolve",
         label: "clear a stuck dialog (close the Things window and reopen it)",
@@ -1676,7 +1877,14 @@ async function closeReopenRung(run, expected, owner, blind = false) {
     }, STEP_TIMEOUT_MS);
     if (blind)
         return { state: "cleared-blind", how: "window-close", ...owner };
-    const after = await readUiState(run, STEP_TIMEOUT_MS);
+    if (inspectionStalled) {
+        const kind = expected === null ? {} : { sheetKind: expected };
+        if (!(await sheetStillOpen(run))) {
+            return { state: "dismissed", how: "window-close", ...kind, ...owner, unverified: true };
+        }
+        return { state: "may-remain", ...kind, ...owner, unverified: true };
+    }
+    const after = await readUiState(run, CENSUS_TIMEOUT_MS);
     if (after === null || !after.inspectable) {
         return { state: "cleared-blind", how: "window-close", ...owner };
     }
@@ -1965,7 +2173,7 @@ async function defaultRun(command, timeoutMs) {
  * nothing, and changes no state; see src/write/vectors/ui-state.ts.
  */
 export function readLiveUiState(run = defaultRun) {
-    return readUiState(run, STEP_TIMEOUT_MS);
+    return readUiState(run, CENSUS_TIMEOUT_MS);
 }
 /**
  * Wrap the dispatch seam so every osascript hop is recorded. The last-dispatched
@@ -2053,6 +2261,13 @@ export function judgeFocusGuard(state, expectedSheet, label) {
         return refuse("the window and focus state could not be read, so there is no proof the input would reach " +
             "Things — nothing was sent");
     }
+    // #629: a probe that did not come back is a DIAGNOSTIC, not a state. Say so
+    // in those words, name what could not be established, and route the drive
+    // straight to its cleanup — the caller must not read this as "retry".
+    if (censusUnverifiable(state)) {
+        return refuse(`the window state inspection timed out — treating the dialog as unverifiable (${describeUnprovenProbes(state)}). Nothing was sent, and the dialog this command opened is being closed. Check that Things ` +
+            "is responding, then run the same command again");
+    }
     if (!state.inspectable) {
         return refuse(`${describeFocusOwner(state)}. Input sent now would go to it, not to Things — nothing was ` +
             "sent. Answer or dismiss the system dialog, then run the same command again");
@@ -2079,19 +2294,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, STEP_TIMEOUT_MS);
         // 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",
@@ -2100,11 +2328,43 @@ function guardedRun(inner, latch) {
                 frontmost: state?.frontmostApp ?? null,
                 sheetKind: state?.sheetKind ?? null,
                 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);
     };
 }
@@ -2127,6 +2387,10 @@ function dialogNoun(kind) {
  */
 export function describeCleanup(clear) {
     const owner = clear.focusOwner === undefined ? "" : ` (${clear.focusOwner} when cleanup started)`;
+    // #629: when the window-state inspection stalled, the cleanup still ran and
+    // still proved its outcome — through the narrower addressed read. Say which
+    // it was, so nobody reads "confirmed closed" as more than it is.
+    const how = clear.unverified === true ? " (the window state could not be inspected)" : "";
     switch (clear.state) {
         case "none":
             return "No dialog was left open in Things.";
@@ -2135,7 +2399,7 @@ export function describeCleanup(clear) {
                 ? `${dialogNoun(clear.sheetKind)} was closed with its own Cancel button`
                 : clear.how === "escape"
                     ? `${dialogNoun(clear.sheetKind)} was dismissed with Escape`
-                    : `${dialogNoun(clear.sheetKind)} was cleared by closing and reopening the Things window`}, confirmed closed${owner}.`;
+                    : `${dialogNoun(clear.sheetKind)} was cleared by closing and reopening the Things window`}, confirmed closed${how}${owner}.`;
         case "cleared-blind":
             return ("Things had no window reachable on the current screen (the Mac may be locked, or a" +
                 " full-screen app is covering the desktop), so the open dialog could not be confirmed" +
@@ -2178,40 +2442,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) };
@@ -2301,8 +2568,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",
@@ -2418,12 +2683,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`,
@@ -2552,11 +2818,12 @@ async function drive(recipe, rawRun, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS,
     // Every step below dispatches through the PER-STEP FOCUS GUARD (issue #620);
     // the latch records the dialog this drive is observed driving, so the cleanup
     // ladder can tell our own half-open dialog from one the user opened after us.
-    const latch = { sheet: null };
+    const latch = { sheet: null, inspectionStalled: false };
     const run = guardedRun(rawRun, latch);
     // The cleanup ladder audits for itself (it is what decides whether a keystroke
-    // may be sent at all), so it runs OUTSIDE the guard.
-    const clearNow = () => clearDialog(rawRun, latch.sheet);
+    // may be sent at all), so it runs OUTSIDE the guard — and it is told when the
+    // inspection has already stalled, so it never re-runs it (issue #629).
+    const clearNow = () => clearDialog(rawRun, latch.sheet, latch.inspectionStalled);
     const done = [];
     // The overall-drive WATCHDOG (TRACE1 #487). A drive can outlast the caller's
     // own timeout on a slow production database (large + Things-Cloud syncing
@@ -2587,6 +2854,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,
@@ -2620,7 +2888,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 {
@@ -2654,9 +2926,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
@@ -2681,7 +2953,12 @@ async function drive(recipe, rawRun, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS,
     //      directly, for every recipe, before anything is pressed — and a dialog
     //      standing here also means the app is ignoring scripted changes app-wide
     //      and holding Things Cloud sync, which is the operator's real problem.
-    const startState = await readUiState(rawRun, STEP_TIMEOUT_MS);
+    const startState = await readUiState(rawRun, CENSUS_TIMEOUT_MS);
+    // An inspection that stalls at the very first hop is remembered, so a later
+    // failure's cleanup does not go asking it again (issue #629). The preflight
+    // itself stays permissive — only a POSITIVE sighting refuses (MODALX1 §7).
+    if (censusUnverifiable(startState))
+        latch.inspectionStalled = true;
     if (startState !== null && startState.inspectable && startState.sheetOpen) {
         return refusal(`ui preflight refused: a dialog is already open in Things (${startState.sheetKind}${startState.sheetDepth > 1 ? `, on top of ${startState.sheetDepth - 1} more` : ""}), most likely left over from an earlier command or opened by hand. While one is open the ` +
             "app disables its menu bar, ignores keyboard input aimed at anything else, and " +
@@ -2693,7 +2970,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
@@ -2754,9 +3037,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();
@@ -2794,19 +3079,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.
@@ -2922,39 +3199,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) {
@@ -3031,7 +3281,7 @@ export function createUiVector(config, run = defaultRun, aux = {}) {
         // composite's FIRST leg mints a row through the URL scheme, which sails
         // straight past an open dialog — and every AppleScript leg after it then
         // fails, leaving a copy behind. The orchestrator asks this BEFORE it seeds.
-        probeUiState: () => readUiState(tracedRun, STEP_TIMEOUT_MS),
+        probeUiState: () => readUiState(tracedRun, CENSUS_TIMEOUT_MS),
         // Pre-seed gate seam for the promote orchestrators (SESSGATE, #480): probe the
         // live session BEFORE they seed a row, so a locked/full-screen session refuses
         // with zero mutation. Present regardless of `enabled` (the orchestrator has