things-api 0.16.0 → 0.18.0

package/dist/write/vectors/ui.js

@@ -26,13 +26,23 @@
  * v1 shells out to `osascript` with ONE stable command shape per primitive.
  */
 import { execFile } from "node:child_process";
+import { DEFAULT_UI_DRIVE_BUDGET_MS } from "../../config.js";
+import { osaExec } from "../../deputy/osa.js";
+import { noteInflightStep, trace, traceActive, tracePath } from "../../trace/tracer.js";
 import { UI_DRIVE_OPS } from "../operations.js";
 import { escapeAppleScript } from "./applescript.js";
+import { createReachabilityCache, H_UI_SESSION_UNREACHABLE, probeSessionReachability, } from "./session-reachability.js";
 import { certificationOf } from "./ui-certification.js";
 import { driveSidebarAreaReorder, jxaSidebarSnapshotScript } from "./ui-drag.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). */
+/**
+ * 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
@@ -45,9 +55,22 @@ 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).
+ * 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.
  */
-const SETTLE_AFTER_REVEAL_MS = 1500;
+const SETTLE_AFTER_REVEAL_MS = 1000;
+/**
+ * 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
+ * dependants). Refused, never guessed: the two shapes address DIFFERENT controls
+ * at the same index.
+ */
+const SHAPE_UNPROBED = "the Repeat dialog's shape was never measured, so this control's address is unknown (recipe bug)";
 const SE = `tell application "System Events" to tell process "Things3"`;
 /** resolve-element: does the element exist right now? Returns "true"/"false". */
 export function axResolveScript(path) {
@@ -98,6 +121,39 @@ export function axSetValueScript(path, value, attempts = 3) {
   error "field did not hold value \\"${v}\\" after ${n} attempt(s); last shown: " & ((value of tf) as text)
 end tell`;
 }
+/**
+ * ensure-checkbox: converge a dialog checkbox to a target state through a
+ * DETERMINISTIC CLOSED LOOP (RRD1, determinism doctrine) — never a blind toggle.
+ * It reads the checkbox's `AXValue` (0 = unchecked, 1 = checked), presses it ONLY
+ * when the observed value differs from `target`, then RE-READS to confirm the new
+ * value equals `target`. A press that did not register (or a value that has not
+ * settled) is retried a bounded number of times; if it never converges the script
+ * FAILS CLOSED (an `error`, i.e. a transport failure the pipeline re-verifies).
+ *
+ * This is what makes the "Add deadlines" / "Add reminders" checkboxes safe on a
+ * PRE-POPULATED reschedule dialog: the dialog opens with the item's CURRENT
+ * deadline/reminder state already ticked, so the old unconditional `click`
+ * FLIPPED an already-correct box the wrong way — the live #493-adjacent bug where
+ * a blind "Add deadlines" press UNCHECKED an already-deadlined rule and hid the
+ * "start N days earlier" field, collapsing the drive. Reading before pressing
+ * makes an already-correct box a no-op. One stable command shape per primitive.
+ */
+export function axEnsureCheckboxScript(path, target, attempts = 3) {
+    const want = target ? 1 : 0;
+    const n = Math.max(1, Math.trunc(attempts));
+    return `${SE}
+  set cb to (${path})
+  repeat ${n} times
+    set cur to (value of cb) as integer
+    if cur is ${want} then return "OK"
+    click cb
+    delay 0.2
+  end repeat
+  set cur to (value of cb) as integer
+  if cur is ${want} then return "OK"
+  error "checkbox did not converge to ${want} after ${n} attempt(s); still " & cur
+end tell`;
+}
 /**
  * select-popup: choose an item in a pop-up button by NAME. Setting `value` on a
  * Things pop-up button is a silent no-op (UIC1 / UI2-i) — the control must be
@@ -142,6 +198,270 @@ export function axSelectPopupCandidatesScript(path, values) {
   error "none of the candidate menu items exist: " & {${list}}
 end tell`;
 }
+/**
+ * probe-dialog-shape: MEASURE which Repeat dialog is open (RDLG2) — the whole
+ * version fork, decided by STRUCTURE rather than by the app version, so the
+ * recipe self-selects on any host and a future redesign refuses instead of
+ * silently pressing the wrong control:
+ *
+ *  - `next-popup` (Things 3.23+) — the first occurrence is an `AXPopUpButton`
+ *    listing the rule's own upcoming occurrences. It sits between Ends and every
+ *    per-frequency control, so weekday / monthly / yearly pop-ups are one index
+ *    further along.
+ *  - `legacy` (Things ≤ 3.22) — the first occurrence is a free-form
+ *    `AXDateTimeArea`, and the per-frequency controls follow Ends directly.
+ *
+ * The discriminator is the CONTROL CLASS on the `Next:` row, not the presence of
+ * the label: RDLG2d measured Things 3.22.14 and found it carries the same
+ * `Next:` static text (and the same occurrence-preview line) as 3.23 — only the
+ * control beside it changed. So the probe reads the label's row position and asks
+ * what kind of control shares that row, which also keeps it independent of the
+ * dialog's Ends state (an `Ends: on date` bound adds a SECOND date area, on a
+ * different row, in both shapes). Each branch is a POSITIVE match, so an
+ * unrecognized third dialog returns "unknown" and the driver refuses. Labels are
+ * pinned English, exactly like every other selector here.
+ */
+export function axProbeDialogShapeScript(groupPath, rowTolerance = 8) {
+    const tol = Math.max(1, Math.trunc(rowTolerance));
+    return `${SE}
+  set g to (${groupPath})
+  set nextY to missing value
+  set nStatic to (count of static texts of g)
+  repeat with i from 1 to nStatic
+    set v to ""
+    try
+      set v to (value of static text i of g) as text
+    end try
+    if v is "Next:" then
+      set p to position of static text i of g
+      set nextY to item 2 of p
+    end if
+  end repeat
+  if nextY is missing value then return "unknown"
+  set nPop to (count of pop up buttons of g)
+  repeat with i from 1 to nPop
+    set p to position of pop up button i of g
+    set dy to (item 2 of p) - nextY
+    if dy < 0 then set dy to -dy
+    if dy <= ${tol} then return "next-popup"
+  end repeat
+  try
+    set areas to (every UI element of g whose role is "AXDateTimeArea")
+    repeat with i from 1 to (count of areas)
+      set p to position of (item i of areas)
+      set dy to (item 2 of p) - nextY
+      if dy < 0 then set dy to -dy
+      if dy <= ${tol} then return "legacy"
+    end repeat
+  end try
+  return "unknown"
+end tell`;
+}
+/**
+ * select-next-occurrence: set the first occurrence through the Things 3.23
+ * `Next:` POP-UP (RDLG2). 3.23 replaced the free-form first-occurrence date area
+ * with a bounded MENU — `Today`, then the rule's own upcoming occurrences, then a
+ * `More…` item whose submenu carries the next hundred, cascading further the same
+ * way. Two consequences this script encodes:
+ *
+ *  - a requested date is reachable ONLY if the rule itself produces it (or it is
+ *    today): the menu offers nothing else, so an OFF-RULE first occurrence — free
+ *    to set on ≤3.22 — is UNEXPRESSIBLE in this dialog and must fail closed with
+ *    a named reason rather than land some neighbouring date;
+ *  - item titles are localized (`Sun, Jul 12, 2026`), so the match is made by
+ *    PARSING each title to a date (with a leading-weekday retry) and comparing
+ *    calendar components — never by rebuilding the app's display string.
+ *
+ * The cascade is walked to a bounded depth; the click is verified by reading the
+ * pop-up's value back and requiring it to equal the clicked item's own title
+ * (the fail-closed read-back the ANCH2/YANCH1 date drives established).
+ */
+export function axSelectNextOccurrenceScript(popupPath, isoDate, maxLevels = 6) {
+    const [y, m, d] = isoDate.split("-").map((part) => Number(part));
+    const levels = Math.max(1, Math.trunc(maxLevels));
+    return `on parsedYMD(t)
+  set s to t as text
+  try
+    set theDate to date s
+    return {year of theDate, (month of theDate) as integer, day of theDate}
+  end try
+  try
+    set ofs to offset of ", " in s
+    if ofs > 0 then
+      set theDate to date (text (ofs + 2) thru -1 of s)
+      return {year of theDate, (month of theDate) as integer, day of theDate}
+    end if
+  end try
+  return missing value
+end parsedYMD
+
+set wantY to ${y}
+set wantM to ${m}
+set wantD to ${d}
+set rightNow to current date
+set isToday to ((year of rightNow) is wantY and ((month of rightNow) as integer) is wantM and (day of rightNow) is wantD)
+${SE}
+  set pu to (${popupPath})
+  repeat 20 times
+    if (exists menu 1 of pu) then exit repeat
+    click pu
+    delay 0.3
+  end repeat
+  set theMenu to menu 1 of pu
+  set clickedTitle to ""
+  set levelsSeen to 0
+  if isToday then
+    set nms to name of every menu item of theMenu
+    if (count of nms) > 0 then
+      set t1 to item 1 of nms
+      if t1 is not missing value then
+        if (my parsedYMD(t1)) is missing value then
+          set clickedTitle to t1 as text
+          click menu item 1 of theMenu
+        end if
+      end if
+    end if
+  end if
+  repeat ${levels} times
+    if clickedTitle is not "" then exit repeat
+    set levelsSeen to levelsSeen + 1
+    set nms to name of every menu item of theMenu
+    set hit to 0
+    repeat with i from 1 to (count of nms)
+      set nm to item i of nms
+      if nm is not missing value then
+        set ymd to my parsedYMD(nm)
+        if ymd is not missing value then
+          if (item 1 of ymd) is wantY and (item 2 of ymd) is wantM and (item 3 of ymd) is wantD then
+            set hit to i
+            exit repeat
+          end if
+        end if
+      end if
+    end repeat
+    if hit > 0 then
+      set clickedTitle to (item hit of nms) as text
+      click menu item hit of theMenu
+      exit repeat
+    end if
+    set lastI to (count of nms)
+    if lastI is 0 then exit repeat
+    if (item lastI of nms) is missing value then exit repeat
+    set deeper to missing value
+    try
+      set deeper to menu 1 of menu item lastI of theMenu
+    end try
+    if deeper is missing value then
+      try
+        click menu item lastI of theMenu
+        delay 0.5
+        set deeper to menu 1 of menu item lastI of theMenu
+      end try
+    end if
+    if deeper is missing value then exit repeat
+    set theMenu to deeper
+  end repeat
+  if clickedTitle is "" then
+    key code 53
+    error "select-next-occurrence: this Repeat dialog offers only the rule's own upcoming occurrences (and today) as the first occurrence, and ${isoDate} is not one of them — searched " & levelsSeen & " level(s) of the Next: menu. Ask for a date the rule actually produces, or change the rule."
+  end if
+  delay 0.4
+  set shown to (value of pu) as text
+  if shown is not clickedTitle then
+    error "select-next-occurrence: the Next: pop-up committed \\"" & shown & "\\", not the requested \\"" & clickedTitle & "\\" — the selection did not take"
+  end if
+  return "OK"
+end tell`;
+}
+/**
+ * converge-weekdays: drive the weekly dialog's weekday ROWS onto an exact target
+ * set through a deterministic closed loop (RDLG2 — the RRD1 fix).
+ *
+ * The shipped drive set the FIRST weekday row and then pressed "+" and re-drove
+ * THE SAME row index per extra weekday, which on a PRE-POPULATED reschedule
+ * dialog left the rule's existing weekdays untouched: `{mon,wed}` retargeted to
+ * `{tue,thu,sat}` committed `{mon,tue,thu,sat}` (VMQ1 cell 2Tb — caught only by
+ * the write pipeline's verify). It also had no way to SHRINK a set.
+ *
+ * The loop instead: (1) read the live row count; (2) press the row-add button —
+ * the smaller-x button of a weekday row, resolved from live geometry rather than
+ * a pinned index, because the row buttons enumerate in an unstable order — until
+ * there are at least as many rows as target weekdays; (3) assign EVERY row from
+ * the target set, cycling, so a surplus row duplicates a target weekday instead
+ * of keeping a stale one (the app stores the weekdays as a SET, so duplicates
+ * collapse on commit — this is what makes shrinking possible without the
+ * remove button); (4) read every row back and require the set to match exactly.
+ * Anything else errors — the pipeline re-verifies against the DB regardless.
+ *
+ * `base` is the 1-based group pop-up index of the first weekday row (2 on the
+ * legacy dialog, 3 once the 3.23 `Next:` pop-up sits in front of them).
+ */
+export function axConvergeWeekdaysScript(groupPath, base, titles) {
+    const list = titles.map((t) => `"${escapeAppleScript(t)}"`).join(", ");
+    const b = Math.max(1, Math.trunc(base));
+    return `set wantList to {${list}}
+set baseIx to ${b}
+${SE}
+  set g to (${groupPath})
+  set k to (count of wantList)
+  repeat 14 times
+    set n to (count of pop up buttons of g) - baseIx + 1
+    if n >= k then exit repeat
+    set nb to (count of buttons of g)
+    if nb is 0 then error "converge-weekdays: the dialog exposes no weekday row button, so a second weekday cannot be added"
+    set bestI to 0
+    set bestX to 1000000
+    repeat with i from 1 to nb
+      set p to position of button i of g
+      set px to item 1 of p
+      if px < bestX then
+        set bestX to px
+        set bestI to i
+      end if
+    end repeat
+    click button bestI of g
+    delay 0.5
+  end repeat
+  set n to (count of pop up buttons of g) - baseIx + 1
+  if n < k then error "converge-weekdays: the dialog would not grow to " & k & " weekday row(s) — it stopped at " & n
+  repeat with i from 1 to n
+    set wi to ((i - 1) mod k) + 1
+    set wantVal to item wi of wantList
+    set pu to pop up button (baseIx + i - 1) of g
+    if ((value of pu) as text) is not wantVal then
+      repeat 20 times
+        if (exists menu 1 of pu) then exit repeat
+        click pu
+        delay 0.3
+      end repeat
+      if not (exists menu item wantVal of menu 1 of pu) then
+        key code 53
+        error "converge-weekdays: the weekday pop-up offers no item \\"" & wantVal & "\\" (the app may not be in English)"
+      end if
+      click menu item wantVal of menu 1 of pu
+      delay 0.4
+    end if
+  end repeat
+  set absent to ""
+  repeat with wi from 1 to k
+    set wantVal to item wi of wantList
+    set seen to false
+    repeat with i from 1 to n
+      if ((value of pop up button (baseIx + i - 1) of g) as text) is wantVal then set seen to true
+    end repeat
+    if not seen then set absent to absent & wantVal & " "
+  end repeat
+  set strays to ""
+  repeat with i from 1 to n
+    set v to (value of pop up button (baseIx + i - 1) of g) as text
+    if wantList does not contain v then set strays to strays & v & " "
+  end repeat
+  if absent is not "" or strays is not "" then
+    error "converge-weekdays: the weekday rows did not converge — missing: " & absent & "| unexpected: " & strays
+  end if
+  return "OK"
+end tell`;
+}
 /**
  * select-row: select a PROJECT row by title, purely via AX (UIC4-a). Walks the
  * content table's rows, issues the row `select` action on each (which REPLACES
@@ -213,6 +533,41 @@ export function axSelectHeadingRowScript(tablePath, ordinal) {
 end tell
 return "NOMATCH"`;
 }
+/**
+ * assert-eligible: after a `things:///show?id=` reveal, VERIFY the target to-do
+ * is genuinely the sole selection AND that the menu item that acts on it is
+ * enabled — before the menu is pressed (ADR1, issue #480). The reveal is assumed
+ * to select the row, but on some surfaces it can navigate without selecting; an
+ * AXPress on the resulting DISABLED `Items ▸ Repeat…` is a silent no-op, so the
+ * dialog never opens and the drive dies far downstream at the dialog-wait timeout
+ * with no hint of the real cause. Reading `Things3 → id of selected to dos` is
+ * uuid-precise (never a fuzzy title match), so a match GUARANTEES the intended row
+ * is selected. Returns "OK" only when exactly the target is selected and the menu
+ * item is enabled; otherwise a diagnostic (`NOTSEL…`/`WRONGSEL…`/`DISABLED…`)
+ * naming expected vs observed. Pure System Events + Things scripting, background-
+ * capable. One stable command shape per primitive.
+ */
+export function axAssertEligibleScript(targetUuid, menuItemPath) {
+    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"`;
+}
 /** activate: foreground Things (the fallback preamble step). */
 export function axActivateScript() {
     return `tell application "Things3" to activate`;
@@ -232,6 +587,29 @@ export function axKeyScript(keys) {
 export function axAbortScript() {
     return `tell application "System Events" to key code 53`; // Escape
 }
+/**
+ * The PROVEN app-level clearance / relocation maneuver (SESSGATE, #480, live-host
+ * recovery): close the front Things window — which takes an attached modal sheet
+ * with it — then reopen and activate. Runs entirely through Things' own
+ * AppleScript dictionary, so it works WITHOUT the Accessibility tree (the exact
+ * property needed when the session is AX-blind). Two uses:
+ *   - CLEANUP: clear a stuck modal sheet a failed drive left open (unblocks the
+ *     app-wide AppleScript-mutation freeze that sheet imposes);
+ *   - RELOCATION: pull a window that was on another Space back to the current one
+ *     so its dialog can open AX-reachably (the wrong-Space recovery branch).
+ * `reopen` restores the default window on the CURRENT Space; `activate` foregrounds
+ * it. Returns "OK".
+ */
+export function axCloseReopenActivateScript() {
+    return `tell application "Things3"
+  try
+    close window 1
+  end try
+  reopen
+  activate
+end tell
+return "OK"`;
+}
 /**
  * sheet-open probe: is a modal SHEET attached to the Things standard window, OR
  * a detached repeat-editor / popover window (an `AXUnknown` that is not the
@@ -262,19 +640,86 @@ async function sheetStillOpen(run) {
     return !(res.ok && res.stdout.trim() === "false");
 }
 /**
- * Send Escape and VERIFY the sheet/popover is gone (0½ defect (d): the abort
- * must never claim dismissal it did not confirm). Retries Escape ONCE if the
- * first is not honored. Returns whether dismissal was verified — the caller
- * words its partial-state report accordingly (fail-closed: on an unverifiable
- * dismissal it must warn the sheet may remain open).
+ * Clear a half-open sheet/popover a failed drive left behind — HONESTLY (SESSGATE
+ * #480 fix; supersedes the old verifiedAbort, whose AX-blind sheet probe returned
+ * "gone" it could not actually see, letting the still-open modal freeze the
+ * app-wide AppleScript mutations the caller then attempted — the auto-trash
+ * silent-noop). Escape first; then:
+ *   - AX-BLIND (a not-reachable probe): Escape may never have reached the sheet
+ *     and the sheet probe cannot see it, so run the app-level close+reopen that
+ *     works blind (it takes the stuck sheet with the window). Reported as
+ *     "cleared-blind" — never falsely "confirmed gone".
+ *   - REACHABLE: the sheet probe is trustworthy — confirm the dismissal (retry
+ *     Escape once), and if it will not go, warn "may remain".
  */
-async function verifiedAbort(run) {
+async function clearDialog(run) {
     const escape = () => run({ primitive: "key", label: "abort (Escape)", script: axAbortScript() }, STEP_TIMEOUT_MS);
     await escape();
+    const reach = await probeSessionReachability(run, STEP_TIMEOUT_MS);
+    if (!reach.reachable) {
+        // Cannot trust Escape or the sheet probe while AX-blind — use the proven
+        // app-level maneuver, which clears a stuck sheet without the Accessibility tree.
+        await run({
+            primitive: "resolve",
+            label: "clear a stuck dialog (close the Things window and reopen it)",
+            script: axCloseReopenActivateScript(),
+        }, STEP_TIMEOUT_MS);
+        return { state: "cleared-blind" };
+    }
     if (!(await sheetStillOpen(run)))
-        return { dismissed: true };
+        return { state: "dismissed" };
     await escape(); // one retry
-    return { dismissed: !(await sheetStillOpen(run)) };
+    return { state: (await sheetStillOpen(run)) ? "may-remain" : "dismissed" };
+}
+/**
+ * The dialog-class reachability GATE (SESSGATE, #480), run AFTER the reveal/
+ * activate preamble (which surfaces a window in a healthy session) and BEFORE any
+ * menu press. Three outcomes matched to the live session state:
+ *   - reachable                  → proceed;
+ *   - not reachable, "session"   → REFUSE (locked screen / full-screen Space —
+ *                                  the certain-failure case): block, zero mutation;
+ *   - not reachable, "window"    → RELOCATE: only Things' window is off the
+ *                                  current Space, so run the app-level close+reopen
+ *                                  that pulls it back, then RE-PROBE closed-loop.
+ *                                  Reachable now → proceed (disclosed); still not →
+ *                                  block with the Space remediation.
+ */
+async function ensureWindowReachable(run, reachCache) {
+    // First probe MAY be served from the pre-seed gate's memo (PERF1) — but only a
+    // reachable verdict is ever memoized, so every refusal/relocation below is still
+    // decided on a fresh probe (see ReachabilityProbeCache).
+    const first = await reachCache.probe(run, STEP_TIMEOUT_MS);
+    if (first.reachable)
+        return { ok: true, relocated: false };
+    if (first.scope === "session")
+        return { ok: false, verdict: first };
+    // scope "window": Things' window is on another Space (or absent) while the
+    // session is otherwise fine — try to bring it to the current Space, then re-probe.
+    await run({
+        primitive: "resolve",
+        label: "move the Things window to the current desktop",
+        script: axCloseReopenActivateScript(),
+    }, STEP_TIMEOUT_MS);
+    // The relocation just changed window state — drop any memo and re-probe LIVE
+    // (a closed-loop verify of the maneuver, never a cached verdict).
+    reachCache.invalidate();
+    const second = await probeSessionReachability(run, STEP_TIMEOUT_MS);
+    if (second.reachable)
+        return { ok: true, relocated: true };
+    return { ok: false, verdict: second.reachable ? first : second };
+}
+/** The blocked ExecuteResult a dialog-class op returns when the session is unreachable. */
+function blockedReachability(verdict) {
+    return {
+        exitCode: 4,
+        stdout: "",
+        stderr: `${verdict.detail} ${verdict.remediation}`,
+        blocked: {
+            hazard: H_UI_SESSION_UNREACHABLE,
+            detail: verdict.detail,
+            remediation: verdict.remediation,
+        },
+    };
 }
 /**
  * resolve-frame: read the element's on-screen frame (top-left origin, points)
@@ -314,40 +759,100 @@ function clickPointCommand(x, y, label) {
     return { primitive: "click-point", label, lang: "javascript", script: jxaClickScript(x, y) };
 }
 /**
- * set-datetime: set the Repeat dialog's `AXDateTimeArea` (reminder time / "ends
- * on date" bound) via the ObjC AX bridge. Things' date/time control holds an
- * NSDate, and System Events cannot write it (`set value … to <date>` → -10000,
- * UIC6), so — like the mouse-synthesis primitive — this runs in JXA and calls
- * `AXUIElementSetAttributeValue(…, AXValue, <NSDate>)` directly. The control is
- * found by ROLE within Things' front dialog (there is exactly one during a
- * reminder/end-date step; the matrix never sets both at once), polled briefly
- * so it is caught right after the checkbox/pop-up that reveals it, and the
- * script THROWS when absent so the driver fails closed. `spec` is
- * `time:HH:mm` (keep the control's date, overwrite the time-of-day) or
- * `date:YYYY-MM-DD` (overwrite the date at midnight). One stable JXA shape.
+ * set-datetime: set ONE of the Repeat dialog's `AXDateTimeArea` controls via the
+ * ObjC AX bridge. Things' date/time controls hold an NSDate, and System Events
+ * cannot write them (`set value … to <date>` → -10000, UIC6), so — like the
+ * mouse-synthesis primitive — this runs in JXA and calls
+ * `AXUIElementSetAttributeValue(…, AXValue, <NSDate>)` directly.
+ *
+ * A fixed rule can expose up to THREE date areas at once — "Next:" (first
+ * occurrence), "Ends: on date", and the reminder time (ANCH2 census). Targeting
+ * "the first AXDateTimeArea by role" is therefore AMBIGUOUS — that ambiguity
+ * collapsed the series when `--ends-on` added a second area (oddities §8v, now
+ * retracted) and made the reminder look undrivable (UIC6-g, now retracted). This
+ * driver selects DETERMINISTICALLY by `target` (ANCH2, docs/lab/anch2-next-field.md):
+ *   - `reminder` — the only area carrying a time-of-day (the date pickers sit at
+ *     midnight); falls back to the bottom-most area if none carry a time.
+ *   - `next` — the TOP (smallest-y) midnight date picker.
+ *   - `ends` — the BOTTOM (largest-y) midnight date picker (present only once
+ *     "Ends: on date" is selected).
+ * The areas are polled briefly (revealed a beat after the checkbox/pop-up), and
+ * the script THROWS a NAMED, structured error when the addressed control is
+ * absent — reporting which target was sought and the FULL date-area inventory of
+ * the current dialog state (count + per-area y / time-of-day) — so a dialog shape
+ * that does not present the target (e.g. the deadline-mode variant, YANCH1 #493)
+ * fails closed with an actionable message, never an uncaught `-[__NSArray0
+ * objectAtIndex:]` (-2700) from indexing an empty collection. It then READS THE
+ * CONTROL BACK after the write and throws if the committed value differs from the
+ * request: a control that silently rejects the write (the macOS error beep the
+ * user hears) must fail the step loudly, never leave a garbled/default value to be
+ * verified as ok (YANCH1; UIC6-g refuse-rather-than-commit precedent). `spec` is
+ * `time:HH:mm` (keep the date, set the time-of-day) or `date:YYYY-MM-DD` (set the
+ * calendar date at midnight). One stable JXA shape.
  */
-export function axSetDateTimeScript(spec) {
+export function axSetDateTimeScript(spec, target) {
     return `ObjC.import('Foundation'); ObjC.import('AppKit'); ObjC.import('ApplicationServices');
 function attr(el,name){ var out=Ref(); if($.AXUIElementCopyAttributeValue(el,$(name),out)!==0) return null; return ObjC.castRefToObject(out[0]); }
 function rolestr(el){ var v=attr(el,'AXRole'); return v? v.js : ''; }
 function kids(el){ var c=attr(el,'AXChildren'); if(!c) return []; var a=[]; for(var i=0;i<c.count;i++) a.push(c.objectAtIndex(i)); return a; }
-function find(el,role,depth){ if(depth<0) return null; if(rolestr(el)===role) return el; var ks=kids(el); for(var i=0;i<ks.length;i++){ var r=find(ks[i],role,depth-1); if(r) return r;} return null; }
+function collect(el,role,depth,out){ if(depth<0) return; if(rolestr(el)===role) out.push(el); var ks=kids(el); for(var i=0;i<ks.length;i++) collect(ks[i],role,depth-1,out); }
+function subrole(el){ var v=attr(el,'AXSubrole'); return v? v.js : ''; }
+function windowsOf(el){ var c=attr(el,'AXWindows'); if(!c) return []; var a=[]; for(var i=0;i<c.count;i++) a.push(c.objectAtIndex(i)); return a; }
+function sizeWH(el){ var s=attr(el,'AXSize'); if(!s) return null; var d=ObjC.castRefToObject($.CFCopyDescription(s)).js; var mw=String(d).match(/w:([-0-9.]+)/); var mh=String(d).match(/h:([-0-9.]+)/); return (mw&&mh)? {w:+mw[1], h:+mh[1]} : null; }
+// Resolve the Repeat-dialog SHELL so the AXDateTimeArea collect walks only its
+// small subtree — never the app-wide tree, whose main-window list content is the
+// 4.4s app-root descent PERF2 removed (docs/lab/perf2-step-latency.md). The dialog
+// presents in TWO shapes (ui-recipes DIALOG_SHELLS, UIC4-a), tried in the SAME
+// priority order the System-Events pathCandidates use: an attached AXSheet on the
+// standard window (Things frontmost), then a detached top-level AXUnknown window
+// that is not the 40x40 utility window (Things backgrounded). null when neither is
+// present — the caller then falls through to the same named "presents 0 date
+// area(s)" error the app-root walk threw when the dialog was absent.
+function findShell(app){
+  var wins=windowsOf(app);
+  for(var i=0;i<wins.length;i++){ if(subrole(wins[i])==='AXStandardWindow'){ var sh=[]; collect(wins[i],'AXSheet',3,sh); if(sh.length) return sh[0]; } }
+  for(var i=0;i<wins.length;i++){ if(subrole(wins[i])==='AXUnknown'){ var wh=sizeWH(wins[i]); if(!wh || !(wh.w===40 && wh.h===40)) return wins[i]; } }
+  return null;
+}
+function posY(el){ var p=attr(el,'AXPosition'); if(!p) return 0; var d=ObjC.castRefToObject($.CFCopyDescription(p)).js; var m=String(d).match(/y:([-0-9.]+)/); return m? +m[1] : 0; }
+function timeOfDay(el){ var v=attr(el,'AXValue'); if(!v) return -1; var cal=$.NSCalendar.currentCalendar; return cal.componentFromDate($.NSCalendarUnitHour,v)*60 + cal.componentFromDate($.NSCalendarUnitMinute,v); }
+function pick(areas,target){
+  if(areas.length===0) return null;
+  var sorted=areas.slice().sort(function(a,b){ return posY(a)-posY(b); });
+  if(target==='reminder'){
+    var timed=sorted.filter(function(a){ return timeOfDay(a)>0; });
+    return timed.length? timed[timed.length-1] : sorted[sorted.length-1];
+  }
+  var midnight=sorted.filter(function(a){ return timeOfDay(a)===0; });
+  if(midnight.length===0) midnight=sorted;
+  return target==='ends' ? midnight[midnight.length-1] : midnight[0];
+}
+function inv(areas){ var s=[]; for(var i=0;i<areas.length;i++){ s.push('#'+i+'(y='+Math.round(posY(areas[i]))+',tod='+timeOfDay(areas[i])+')'); } return areas.length? s.join(' ') : '(none)'; }
+function ymdStr(el,cal){ var v=attr(el,'AXValue'); if(!v) return null; var y=cal.componentFromDate($.NSCalendarUnitYear,v), m=cal.componentFromDate($.NSCalendarUnitMonth,v), dd=cal.componentFromDate($.NSCalendarUnitDay,v); return y+'-'+('0'+m).slice(-2)+'-'+('0'+dd).slice(-2); }
+function hmStr(el,cal){ var v=attr(el,'AXValue'); if(!v) return null; var h=cal.componentFromDate($.NSCalendarUnitHour,v), mi=cal.componentFromDate($.NSCalendarUnitMinute,v); return h+':'+('0'+mi).slice(-2); }
 function run(){
   var apps=$.NSRunningApplication.runningApplicationsWithBundleIdentifier('com.culturedcode.ThingsMac');
   if(!apps || apps.count===0) throw new Error('Things not running');
-  var pid=apps.objectAtIndex(0).processIdentifier;
-  var app=$.AXUIElementCreateApplication(pid);
-  var dt=null;
-  for(var t=0;t<20 && !dt;t++){ dt=find(app,'AXDateTimeArea',16); if(!dt) $.NSThread.sleepForTimeInterval(0.1); }
-  if(!dt) throw new Error('no AXDateTimeArea in the Repeat dialog');
+  var app=$.AXUIElementCreateApplication(apps.objectAtIndex(0).processIdentifier);
+  var target=${JSON.stringify(target)};
   var spec=${JSON.stringify(spec)};
+  // Poll for the addressed area WITHIN THE DIALOG SHELL (PERF2): resolve the sheet
+  // / detached editor first, then collect only its subtree — the app-root descent
+  // this replaced cost ~4.4s on the busy host by walking the main window's list
+  // content. collect is wrapped so a stale-element ObjC exception during traversal
+  // cannot bubble as a raw -2700; pick guards the empty set, so dt is null (never a
+  // crash) when the target is absent. When no shell resolves (dialog absent), areas
+  // stays empty and the loop falls through to the SAME named error below.
+  var areas=[]; var dt=null;
+  for(var t=0;t<20 && !dt;t++){ areas=[]; try{ var shell=findShell(app); if(shell) collect(shell,'AXDateTimeArea',16,areas); }catch(e){ areas=[]; } dt=pick(areas,target); if(!dt) $.NSThread.sleepForTimeInterval(0.1); }
+  if(!dt) throw new Error('set-datetime '+target+': this Repeat-dialog state presents '+areas.length+' date area(s) ['+inv(areas)+'] but none is the '+target+' control — the requested first occurrence / bound cannot be set in this dialog shape');
   var cal=$.NSCalendar.currentCalendar;
   var d;
   if(spec.indexOf('time:')===0){
-    // Set the time-of-day on the control's own (today's) date via the purpose-
-    // built calendar API — component-bag mutation via JXA silently drops the
-    // hour, leaking the current wall-clock hour into the reminder (UIC6).
-    var cur=attr(dt,'AXValue'); if(!cur) throw new Error('date/time control has no value');
+    // Set the time-of-day on the control's own date via the purpose-built
+    // calendar API — component-bag mutation via JXA silently drops the hour,
+    // leaking the current wall-clock hour into the reminder (UIC6).
+    var cur=attr(dt,'AXValue'); if(!cur) throw new Error('set-datetime '+target+': the date/time control has no value to anchor the time on');
     var hm=spec.slice(5).split(':');
     d=cal.dateBySettingHourMinuteSecondOfDateOptions(+hm[0], +hm[1], 0, cur, 0);
   } else if(spec.indexOf('date:')===0){
@@ -358,11 +863,35 @@ function run(){
   } else { throw new Error('bad datetime spec: '+spec); }
   if(!d) throw new Error('could not build date from '+spec);
   var err=$.AXUIElementSetAttributeValue(dt,$('AXValue'),d);
-  if(err!==0) throw new Error('AXValue set failed err='+err);
+  if(err!==0) throw new Error('set-datetime '+target+': the control refused the write (AX err='+err+')');
   $.NSThread.sleepForTimeInterval(0.2);
+  // READ-BACK: a control can accept the AX write (err 0) yet reject the value —
+  // the macOS error beep — leaving its prior/default value. Fail the step loudly
+  // rather than let a garbled commit verify as ok (YANCH1 #493).
+  if(spec.indexOf('date:')===0){
+    var got=ymdStr(dt,cal); var want=spec.slice(5);
+    if(got!==want) throw new Error('set-datetime '+target+' rejected: the control committed '+(got||'(no value)')+', not the requested '+want+' — the write did not take');
+  } else {
+    var gott=hmStr(dt,cal); var wanth=spec.slice(5).split(':'); var wantt=(+wanth[0])+':'+('0'+(+wanth[1])).slice(-2);
+    if(gott!==wantt) throw new Error('set-datetime '+target+' rejected: the control committed '+(gott||'(no value)')+', not the requested '+wantt+' — the write did not take');
+  }
   return 'OK';
 }`;
 }
+/**
+ * The converge-weekdays step encodes both of its inputs in `value` as
+ * `"<base>|<Weekday>,<Weekday>…"`: the base is the group pop-up index of the
+ * FIRST weekday row, which the dialog SHAPE decides (2 legacy / 3 next-popup),
+ * so it rides the same shape-selected `value` the driver merges in.
+ */
+export function weekdayBaseOf(value) {
+    const base = Number(value.split("|", 1)[0]);
+    return Number.isFinite(base) && base > 0 ? Math.trunc(base) : 2;
+}
+export function weekdayTitlesOf(value) {
+    const rest = value.slice(value.indexOf("|") + 1);
+    return rest.split(",").filter((t) => t !== "");
+}
 /** Parse a resolve-frame "x y w h" line into the frame's center point. */
 export function parseFrameCenter(stdout) {
     const nums = stdout.trim().split(/\s+/).map(Number);
@@ -374,30 +903,64 @@ export function parseFrameCenter(stdout) {
 function revealUrl(uuid) {
     return `things:///show?id=${encodeURIComponent(uuid)}`;
 }
-function defaultRun(command, timeoutMs) {
-    return new Promise((resolve) => {
-        let bin;
-        let args;
-        if (command.primitive === "reveal") {
-            [bin, args] = ["open", [command.url ?? ""]];
-        }
-        else if (command.lang === "javascript") {
-            // JXA (ObjC bridge) for the mouse-synthesis primitive; one stable shape.
-            [bin, args] = ["osascript", ["-l", "JavaScript", "-e", command.script ?? ""]];
-        }
-        else {
-            [bin, args] = ["osascript", ["-e", command.script ?? ""]];
-        }
-        execFile(bin, [...args], { timeout: timeoutMs }, (err, stdout, stderr) => {
-            const timedOut = err !== null && err.killed === true;
-            resolve({
-                ok: err === null,
-                stdout: String(stdout),
-                stderr: String(stderr),
-                ...(timedOut && { timedOut: true }),
+async function defaultRun(command, timeoutMs) {
+    if (command.primitive === "reveal") {
+        // `open` is consent-free (LaunchServices, no AppleEvent) — never routed.
+        return new Promise((resolve) => {
+            execFile("open", [command.url ?? ""], { timeout: timeoutMs }, (err, stdout, stderr) => {
+                const timedOut = err !== null && err.killed === true;
+                resolve({
+                    ok: err === null,
+                    stdout: String(stdout),
+                    stderr: String(stderr),
+                    ...(timedOut && { timedOut: true }),
+                });
             });
         });
-    });
+    }
+    // JXA (ObjC bridge) for the mouse-synthesis primitive; one stable shape.
+    const lang = command.lang === "javascript" ? "javascript" : "applescript";
+    const res = await osaExec(command.script ?? "", { lang, timeoutMs });
+    return {
+        ok: res.exitCode === 0 && res.timedOut !== true,
+        stdout: res.stdout,
+        stderr: res.stderr,
+        ...(res.timedOut === true && { timedOut: true }),
+    };
+}
+/**
+ * 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,
+ * even with tracing off), and — when tracing is on — a `ui-dispatch` start/end
+ * pair lands in the trace carrying the hop's duration and outcome. This
+ * per-osascript granularity is exactly what reconstructs a hang: the timeline
+ * shows which step's osascript was in flight, and for how long, when it stopped
+ * (TRACE1 #487). Overhead when tracing is off is one boolean check + a field write.
+ */
+function tracingRun(inner) {
+    return async (command, timeoutMs) => {
+        noteInflightStep(command.label);
+        if (!traceActive())
+            return inner(command, timeoutMs);
+        const started = Date.now();
+        trace(() => ({
+            phase: "ui-dispatch",
+            event: "start",
+            primitive: command.primitive,
+            label: command.label,
+        }));
+        const res = await inner(command, timeoutMs);
+        trace(() => ({
+            phase: "ui-dispatch",
+            event: "end",
+            primitive: command.primitive,
+            label: command.label,
+            durationMs: Date.now() - started,
+            ok: res.ok,
+            timedOut: res.timedOut === true,
+        }));
+        return res;
+    };
 }
 /** The element paths the preflight canary resolves (static steps only). */
 function canaryPaths(recipe) {
@@ -485,7 +1048,33 @@ export function commandForStep(step, targetUuid) {
                 primitive: "set-datetime",
                 label: step.label,
                 lang: "javascript",
-                script: axSetDateTimeScript(step.value ?? ""),
+                script: axSetDateTimeScript(step.value ?? "", step.dtTarget ?? "next"),
+            };
+        case "ensure-checkbox":
+            return {
+                primitive: "ensure-checkbox",
+                label: step.label,
+                script: axEnsureCheckboxScript(step.path ?? "", step.checkboxTarget === true),
+            };
+        case "probe-dialog-shape":
+            return {
+                primitive: "probe-dialog-shape",
+                label: step.label,
+                script: axProbeDialogShapeScript(step.path ?? ""),
+            };
+        case "select-next-occurrence":
+            return {
+                primitive: "select-next-occurrence",
+                label: step.label,
+                script: axSelectNextOccurrenceScript(step.path ?? "", step.value ?? ""),
+            };
+        case "converge-weekdays":
+            return {
+                primitive: "converge-weekdays",
+                label: step.label,
+                // `value` is "<base index>|<Weekday>,<Weekday>…" — the base index is the
+                // 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 ?? "") };
@@ -501,6 +1090,12 @@ export function commandForStep(step, targetUuid) {
                 label: step.label,
                 script: axSelectHeadingRowScript(step.path ?? "", Number(step.value ?? "0")),
             };
+        case "assert-eligible":
+            return {
+                primitive: "assert-eligible",
+                label: step.label,
+                script: axAssertEligibleScript(step.value ?? targetUuid, step.path ?? ""),
+            };
         case "key":
             return { primitive: "key", label: step.label, script: axKeyScript(step.keys ?? "") };
         case "click-element":
@@ -567,20 +1162,69 @@ async function driveClickElement(step, run) {
     }
     return { ok: true };
 }
-async function drive(recipe, run, aux) {
+async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS, reachCache = createReachabilityCache()) {
     const done = [];
-    // `dismissed`: true = abort verified the sheet gone; false = abort could NOT
-    // confirm dismissal (warn it may remain open — 0½ defect (d): never claim a
-    // dismissal we did not see); undefined = no sheet was opened / no abort ran.
-    const partial = (failed, why, dismissed) => {
+    // The overall-drive WATCHDOG (TRACE1 #487). A drive can outlast the caller's
+    // own timeout on a slow production database (large + Things-Cloud syncing
+    // commits the Repeat dialog several times slower than the lab golden), which
+    // is how #487 fired: the caller's 30s kill left empty stdout and no retained
+    // exit code. This budget lets the CLI give up FIRST — clearing any open dialog
+    // and returning an honest, uncertain-outcome timeout — so the caller always
+    // receives structured output. Checked between steps (per-step execFile
+    // timeouts bound each osascript, so a step boundary is never far off).
+    const driveStart = Date.now();
+    const driveDeadline = driveStart + budgetMs;
+    const overBudget = () => Date.now() >= driveDeadline;
+    const watchdogResult = async (lastStep) => {
+        // Attempt the SESSGATE dialog clearance so the watchdog never leaves a stuck
+        // modal behind (#485), then report honestly. The outcome is UNCERTAIN: a rule
+        // whose OK press was mid-commit could still land — the pipeline re-verifies
+        // and shapes the final result accordingly.
+        const clear = await clearDialog(run);
+        trace(() => ({
+            phase: "watchdog",
+            budgetMs,
+            elapsedMs: Date.now() - driveStart,
+            lastStep,
+            clear: clear.state,
+            completed: done,
+        }));
+        return {
+            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}"`,
+            timedOut: true,
+            watchdog: {
+                budgetMs,
+                elapsedMs: Date.now() - driveStart,
+                lastStep,
+                clear: clear.state,
+                tracePath: tracePath(),
+            },
+        };
+    };
+    // A note prepended to the success summary when the drive had to RELOCATE the
+    // Things window to the current Space to open its dialog (SESSGATE wrong-Space
+    // recovery) — surfaced to the caller as a disclosure warning.
+    let relocationNote = "";
+    // `clear`: how a half-open sheet was cleaned up after a failure (honest — never
+    // claim a dismissal we could not see, SESSGATE #480); undefined = no sheet was
+    // opened / no cleanup ran (a benign preamble/canary failure).
+    const partial = (failed, why, clear) => {
         const base = `ui drive stopped at "${failed}" (${why}). Completed: ${done.join(" → ") || "nothing"}.`;
-        const cleanup = dismissed === true
-            ? " The open sheet/popover was dismissed (Escape, confirmed gone)."
-            : dismissed === false
-                ? " WARNING: a sheet or popover may still be open in Things — Escape did not dismiss it." +
-                    " Dismiss it manually before retrying (a leftover sheet disables the menu bar and will" +
-                    " make the next drive's preflight fail)."
-                : "";
+        const cleanup = clear === undefined
+            ? ""
+            : clear.state === "dismissed"
+                ? " The open sheet/popover was dismissed (Escape, confirmed gone)."
+                : clear.state === "cleared-blind"
+                    ? " 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" +
+                        " through the on-screen layer — the Things window was closed and reopened to clear it," +
+                        " discarding any partially-entered rule. Unlock the Mac or leave the full-screen app" +
+                        " before retrying."
+                    : " WARNING: a sheet or popover may still be open in Things — Escape did not dismiss it." +
+                        " Dismiss it manually before retrying (a leftover sheet disables the menu bar and will" +
+                        " make the next drive's preflight fail).";
         return refusal(base + cleanup);
     };
     // 0. Run the leading reveal/activate preamble BEFORE the canary. The Items
@@ -603,6 +1247,22 @@ async function drive(recipe, run, aux) {
     // 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));
+    // 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
+    //     healthy session) and BEFORE the canary/press (no mutation yet): a locked /
+    //     full-screen session REFUSES (blocked, zero mutation); a window merely on
+    //     another Space is RELOCATED back and disclosed. Menu-only recipes skip this.
+    if (recipe.needsWindowReachability === true) {
+        const reach = await ensureWindowReachable(run, reachCache);
+        if (!reach.ok)
+            return blockedReachability(reach.verdict);
+        if (reach.relocated) {
+            relocationNote =
+                "the Things window was on another desktop, so it was moved to the desktop you're viewing " +
+                    "to open the dialog. ";
+        }
+    }
     // 1. Recipe canary: resolve every statically-reachable element (now that the
     //    target is selected). A miss refuses the whole drive before anything is
     //    pressed. (This is also the localization check: English titles must resolve.)
@@ -629,8 +1289,44 @@ async function drive(recipe, run, aux) {
         }
     }
     // 2. Execute the remaining steps in order; a dynamic element is waited-for.
+    //
+    // `dialogShape` is the Repeat dialog's MEASURED structure (RDLG2), set by the
+    // recipe's `probe-dialog-shape` step and consumed by the steps that address a
+    // control the 3.23 redesign moved or replaced. It stays null on every recipe
+    // that never probes (no shape-dependent step), and any step that needs it while
+    // it is null fails closed rather than guessing an index.
+    let dialogShape = null;
     for (let i = idx; i < recipe.steps.length; i += 1) {
         let step = recipe.steps[i];
+        // Shape-gated step: the recipe emits BOTH the legacy and the 3.23 drive for a
+        // control whose CLASS changed, and only the matching one runs.
+        if (step.onlyShape !== undefined) {
+            if (dialogShape === null) {
+                const clear = await clearDialog(run);
+                return partial(step.label, SHAPE_UNPROBED, clear);
+            }
+            if (step.onlyShape !== dialogShape)
+                continue;
+        }
+        // Shape-selected paths/values (the +1 index shift the 3.23 "Next:" pop-up
+        // introduced, and the weekday-row base index).
+        if (step.shaped !== undefined) {
+            if (dialogShape === null) {
+                const clear = await clearDialog(run);
+                return partial(step.label, SHAPE_UNPROBED, clear);
+            }
+            const override = step.shaped[dialogShape];
+            if (override === undefined) {
+                const clear = await clearDialog(run);
+                return partial(step.label, `this step has no drive for the "${dialogShape}" Repeat dialog (recipe bug)`, clear);
+            }
+            step = { ...step, ...override };
+        }
+        // Overall-drive watchdog: if the budget is spent, stop at THIS step boundary
+        // (the per-step execFile timeouts keep the boundary close), clear any open
+        // dialog, and return the honest uncertain-outcome timeout (TRACE1 #487).
+        if (overBudget())
+            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).
@@ -638,8 +1334,8 @@ async function drive(recipe, run, aux) {
             const ok = await waitForAnyElement(step.pathCandidates ?? [step.path ?? ""], step.label, step.timeoutMs ?? STEP_TIMEOUT_MS, run);
             if (!ok) {
                 // the abort keystroke must land (and be verified) before returning the partial-state report
-                const { dismissed } = await verifiedAbort(run);
-                return partial(step.label, "the expected element never appeared within the timeout", dismissed);
+                const clear = await clearDialog(run);
+                return partial(step.label, "the expected element never appeared within the timeout", clear);
             }
             done.push(step.label);
             continue;
@@ -665,13 +1361,35 @@ async function drive(recipe, run, aux) {
             const effective = await resolveStepPath(step, run);
             if (effective === null) {
                 // dismiss whatever opened (and verify) before reporting
-                const { dismissed } = await verifiedAbort(run);
+                const clear = await clearDialog(run);
                 return partial(step.label, "none of its expected element shapes resolved (neither the attached sheet nor the " +
-                    "detached repeat editor window)", dismissed);
+                    "detached repeat editor window)", clear);
             }
             step = { ...step, path: effective };
         }
         const command = commandForStep(step, recipe.targetUuid);
+        if (step.primitive === "probe-dialog-shape") {
+            // MEASURE the dialog (RDLG2) before any shape-dependent control is touched.
+            // A shape we do not recognize refuses the drive with the dialog cleared —
+            // the same fail-closed posture as a canary miss, and for the same reason:
+            // pressing a structural index into an unknown tree is how a GUI driver
+            // writes the wrong rule.
+            const res = await run(command, STEP_TIMEOUT_MS);
+            const verdict = res.stdout.trim();
+            if (!res.ok || (verdict !== "next-popup" && verdict !== "legacy")) {
+                const clear = await clearDialog(run);
+                return partial(step.label, res.ok
+                    ? 'its first-occurrence row ("Next:") holds neither an occurrence pop-up nor a date ' +
+                        "field, so the dialog matched neither known shape — a Things update has redesigned " +
+                        "it again; nothing was entered into the rule"
+                    : res.timedOut === true
+                        ? "the dialog-shape probe timed out"
+                        : res.stderr.trim() || "the dialog-shape probe failed", clear);
+            }
+            dialogShape = verdict;
+            done.push(`${step.label} (${verdict})`);
+            continue;
+        }
         if (step.primitive === "select-row" || step.primitive === "select-heading-row") {
             // Pure-AX row selection with readback verification (UIC4-a / HEADCERT1):
             // "OK" only when the intended row selected (title readback for a project
@@ -680,7 +1398,7 @@ async function drive(recipe, run, aux) {
             const res = await run(command, STEP_TIMEOUT_MS);
             if (!res.ok || res.stdout.trim() !== "OK") {
                 // clear any transient state (and verify) before reporting
-                const { dismissed } = await verifiedAbort(run);
+                const clear = await clearDialog(run);
                 const noMatch = step.primitive === "select-heading-row"
                     ? "the project view exposed no selectable heading row at the target position — the " +
                         "heading may have been converted/deleted already, or the project's headings changed"
@@ -690,7 +1408,29 @@ async function drive(recipe, run, aux) {
                     ? noMatch
                     : res.timedOut === true
                         ? "the row-selection step timed out"
-                        : res.stderr.trim() || "the row-selection step failed", dismissed);
+                        : res.stderr.trim() || "the row-selection step failed", clear);
+            }
+            done.push(step.label);
+            continue;
+        }
+        if (step.primitive === "assert-eligible") {
+            // ADR1 (#480): fail EARLY + NAMED when the reveal did not land an eligible
+            // selection, rather than letting a disabled-menu no-op surface downstream
+            // as an opaque dialog-wait timeout. The script returns "OK" or a diagnostic
+            // (NOTSEL…/WRONGSEL…/DISABLED…) that IS the human-readable failure reason.
+            // the selection/enabled state must be confirmed before the menu is pressed
+            const res = await run(command, STEP_TIMEOUT_MS);
+            const verdict = res.stdout.trim();
+            if (!res.ok || verdict !== "OK") {
+                // clear any transient state (and verify) before reporting
+                const clear = await clearDialog(run);
+                return partial(step.label, res.ok
+                    ? verdict !== ""
+                        ? verdict
+                        : "the target to-do was not confirmed selected/eligible after the reveal"
+                    : res.timedOut === true
+                        ? "the eligibility check timed out"
+                        : res.stderr.trim() || "the eligibility check failed", clear);
             }
             done.push(step.label);
             continue;
@@ -701,9 +1441,9 @@ async function drive(recipe, run, aux) {
             // the click depends on the UI state the previous step produced
             const outcome = await driveClickElement(step, run);
             if (!outcome.ok) {
-                // dismiss whatever the click opened (and verify) before reporting
-                const dismissed = outcome.needsAbort === true ? (await verifiedAbort(run)).dismissed : undefined;
-                return partial(step.label, outcome.why ?? "the click failed", dismissed);
+                // clear whatever the click opened (honest cleanup) before reporting
+                const clear = outcome.needsAbort === true ? await clearDialog(run) : undefined;
+                return partial(step.label, outcome.why ?? "the click failed", clear);
             }
             done.push(step.label);
             continue;
@@ -711,15 +1451,20 @@ async function drive(recipe, run, aux) {
         // each recipe step depends on the UI state the previous step produced; they cannot be parallelized
         const res = await run(command, STEP_TIMEOUT_MS);
         if (!res.ok) {
-            // dismiss the half-open sheet/popover (and verify) before reporting partial state
-            const dismissed = step.primitive !== "reveal" && step.primitive !== "activate"
-                ? (await verifiedAbort(run)).dismissed
+            // clear the half-open sheet/popover (honest — never claim an unconfirmed
+            // dismissal) before reporting partial state
+            const clear = step.primitive !== "reveal" && step.primitive !== "activate"
+                ? await clearDialog(run)
                 : undefined;
-            return partial(step.label, res.timedOut === true ? "the step timed out" : res.stderr.trim() || "the step failed", dismissed);
+            return partial(step.label, res.timedOut === true ? "the step timed out" : res.stderr.trim() || "the step failed", clear);
         }
         done.push(step.label);
     }
-    return { exitCode: 0, stdout: `drove ${done.length} step(s): ${done.join(" → ")}`, stderr: "" };
+    return {
+        exitCode: 0,
+        stdout: `${relocationNote}drove ${done.length} step(s): ${done.join(" → ")}`,
+        stderr: "",
+    };
 }
 async function waitForElement(command, timeoutMs, run) {
     const deadline = Date.now() + timeoutMs;
@@ -796,6 +1541,17 @@ function disabledMatrix() {
  */
 export function createUiVector(config, run = defaultRun, aux = {}) {
     const enabled = config.ui.enabled;
+    const budgetMs = config.ui.driveBudgetMs ?? DEFAULT_UI_DRIVE_BUDGET_MS;
+    // Every osascript hop runs through the tracing seam: it notes the step on the
+    // in-flight marker (for the signal handler) and, when tracing is on, records a
+    // start/end pair with timing/outcome (TRACE1 #487).
+    const tracedRun = tracingRun(run);
+    // Intra-invocation reachability memo (PERF1), shared between the pre-seed gate
+    // (probeReachability) and the in-drive gate (ensureWindowReachable) so a promote
+    // composite does not probe the session — seconds-long on a busy desktop — twice.
+    // The vector is rebuilt per client-open, so this is naturally scoped to one CLI
+    // invocation; the memo's own TTL bounds reuse for a long-lived programmatic client.
+    const reachCache = createReachabilityCache();
     return {
         id: "ui",
         matrix: enabled ? enabledMatrix() : disabledMatrix(),
@@ -806,8 +1562,14 @@ export function createUiVector(config, run = defaultRun, aux = {}) {
             if (invocation.recipe === undefined) {
                 return refusal("ui invocation carried no recipe (compile bug).");
             }
-            return drive(invocation.recipe, run, aux);
+            return drive(invocation.recipe, tracedRun, aux, budgetMs, reachCache);
         },
+        // 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
+        // already cleared the H-UI-DRIVE ack by the time it consults this). Populates
+        // the memo the in-drive gate reuses (PERF1).
+        probeReachability: () => reachCache.probe(tracedRun, STEP_TIMEOUT_MS),
     };
 }
 //# sourceMappingURL=ui.js.map