things-api 0.17.0 → 0.19.0

package/dist/write/vectors/ui.js

@@ -27,15 +27,22 @@
  */
 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 { H_UI_SESSION_UNREACHABLE, probeSessionReachability, } from "./session-reachability.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
@@ -48,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 = 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 SETTLE_AFTER_REVEAL_MS = 1500;
+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) {
@@ -178,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
@@ -189,6 +473,19 @@ end tell`;
  * selection-landed verification, so a match guarantees the intended row is
  * selected. One stable command shape per primitive.
  *
+ * VMRES1 correction (2026-08-23, golden-v4 / Things 3.23): the readback LAGS the
+ * `select` action, so reading `name of selected to dos` immediately after it can
+ * return the PREVIOUS iteration's selection. A row whose `select` lands nothing
+ * (the blank spacer that follows the project rows) then matched the prior row's
+ * title, the loop returned "OK" one row LATE, and the table was left with NOTHING
+ * selected — `Items ▸ Repeat…` never materialized and the drive died at its wait
+ * (`verify-failed:silent-noop`). It reproduced 3/3 on the second project-repeat
+ * drive of a Things session and 0/2 on the first, which is the signature of a
+ * race, not of app state. Fixed the way the heading sibling below already does
+ * it: settle after `select`, then require `selected of (row i)` — the row THIS
+ * iteration targeted must itself hold the selection — before trusting the title
+ * readback. Evidence: [docs/lab/vmres1-residuals.md](../../../docs/lab/vmres1-residuals.md) §2.
+ *
  * UIC5 correction: the shipped form set the TABLE's `AXSelectedRows` attribute
  * to a one-row list, which is a SILENT NO-OP on Things' content table via System
  * Events (no error, selection never lands). The row `select` action is the
@@ -204,9 +501,12 @@ export function axSelectRowScript(tablePath, title) {
   repeat with i from 1 to n
     try
       select (row i of theTable)
-      tell application "Things3" to set selNames to (name of selected to dos)
-      if (count of selNames) is 1 and ((item 1 of selNames) as text) is "${t}" then
-        return "OK"
+      delay 0.25
+      if (selected of (row i of theTable)) then
+        tell application "Things3" to set selNames to (name of selected to dos)
+        if (count of selNames) is 1 and ((item 1 of selNames) as text) is "${t}" then
+          return "OK"
+        end if
       end if
     end try
   end repeat
@@ -400,8 +700,11 @@ async function clearDialog(run) {
  *                                  Reachable now → proceed (disclosed); still not →
  *                                  block with the Space remediation.
  */
-async function ensureWindowReachable(run) {
-    const first = await probeSessionReachability(run, STEP_TIMEOUT_MS);
+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")
@@ -413,6 +716,9 @@ async function ensureWindowReachable(run) {
         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 };
@@ -506,6 +812,24 @@ function attr(el,name){ var out=Ref(); if($.AXUIElementCopyAttributeValue(el,$(n
 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 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){
@@ -528,11 +852,15 @@ function run(){
   var app=$.AXUIElementCreateApplication(apps.objectAtIndex(0).processIdentifier);
   var target=${JSON.stringify(target)};
   var spec=${JSON.stringify(spec)};
-  // Poll for the addressed area. 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.
+  // 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{ collect(app,'AXDateTimeArea',16,areas); }catch(e){ areas=[]; } dt=pick(areas,target); if(!dt) $.NSThread.sleepForTimeInterval(0.1); }
+  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;
@@ -566,6 +894,20 @@ function run(){
   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);
@@ -577,30 +919,30 @@ 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
@@ -730,6 +1072,26 @@ export function commandForStep(step, targetUuid) {
                 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 ?? "") };
         case "select-row":
@@ -816,7 +1178,7 @@ async function driveClickElement(step, run) {
     }
     return { ok: true };
 }
-async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS) {
+async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS, reachCache = createReachabilityCache()) {
     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
@@ -864,7 +1226,14 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS) {
     // `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 partial = (failed, why, clear, 
+    /**
+     * The failing step's own transport outcome: `true` when its osascript was
+     * killed by its deadline rather than answering. Together with a blind cleanup
+     * this is what separates "the Things window stopped answering" from "the app
+     * answered and refused/did nothing" (#512) — see {@link ExecuteResult.uiUnreachable}.
+     */
+    stepTimedOut = false) => {
         const base = `ui drive stopped at "${failed}" (${why}). Completed: ${done.join(" → ") || "nothing"}.`;
         const cleanup = clear === undefined
             ? ""
@@ -879,7 +1248,28 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS) {
                     : " 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);
+        // #512: name an environment failure as one. A cleanup that had to run BLIND
+        // is direct evidence the session went AX-blind mid-drive; a step killed by
+        // its own deadline is the window not answering. Either way the app was not
+        // 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);
+        if (cause === null)
+            return res;
+        return {
+            ...res,
+            uiUnreachable: {
+                step: failed,
+                cause,
+                ...(clear !== undefined && { clear: clear.state }),
+                remediation: cause === "unreachable"
+                    ? "unlock the Mac, or leave the full-screen app so a Things window is visible on the " +
+                        "desktop you're viewing, then run the same command again"
+                    : "bring Things to the front and check that it is responding, then run the same " +
+                        "command again",
+            },
+        };
     };
     // 0. Run the leading reveal/activate preamble BEFORE the canary. The Items
     //    menu is context-dependent — its Repeat submenu (and the plain "Repeat…"
@@ -893,7 +1283,7 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS) {
         // the preamble steps are strictly sequential (select, then foreground) and each must land before the next
         const res = await run(commandForStep(step, recipe.targetUuid), STEP_TIMEOUT_MS);
         if (!res.ok) {
-            return partial(step.label, res.timedOut === true ? "the step timed out" : res.stderr.trim() || "the step failed");
+            return partial(step.label, res.timedOut === true ? "the step timed out" : res.stderr.trim() || "the step failed", undefined, res.timedOut === true);
         }
         done.push(step.label);
         idx += 1;
@@ -908,7 +1298,7 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS) {
     //     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);
+        const reach = await ensureWindowReachable(run, reachCache);
         if (!reach.ok)
             return blockedReachability(reach.verdict);
         if (reach.relocated) {
@@ -943,8 +1333,39 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS) {
         }
     }
     // 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).
@@ -991,6 +1412,28 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS) {
             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, res.timedOut === true);
+            }
+            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
@@ -1009,7 +1452,7 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS) {
                     ? noMatch
                     : res.timedOut === true
                         ? "the row-selection step timed out"
-                        : res.stderr.trim() || "the row-selection step failed", clear);
+                        : res.stderr.trim() || "the row-selection step failed", clear, res.timedOut === true);
             }
             done.push(step.label);
             continue;
@@ -1031,7 +1474,7 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS) {
                         : "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);
+                        : res.stderr.trim() || "the eligibility check failed", clear, res.timedOut === true);
             }
             done.push(step.label);
             continue;
@@ -1057,7 +1500,7 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS) {
             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", clear);
+            return partial(step.label, res.timedOut === true ? "the step timed out" : res.stderr.trim() || "the step failed", clear, res.timedOut === true);
         }
         done.push(step.label);
     }
@@ -1128,8 +1571,9 @@ function disabledMatrix() {
             disruption: 3,
             validation: "validated",
             notes: "the Accessibility GUI vector is off on this machine — enable it with `things config " +
-                "set ui-enabled true`, then grant Accessibility to this process (see docs/setup.md). " +
-                "It drives the local Things GUI and is intended for a dedicated always-on Mac.",
+                "set ui-enabled true`, then run `things helpers setup --gui`, which grants GUI-driving " +
+                "to the helper pair (the only identity it is granted to). It drives the local Things " +
+                "GUI and is intended for a dedicated always-on Mac.",
         };
     }
     return matrix;
@@ -1147,23 +1591,34 @@ export function createUiVector(config, run = defaultRun, aux = {}) {
     // 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",
+        // Article IV: the pipeline's GUI gate keys on this declaration, never on
+        // the id — see WriteVector.drivesGui.
+        drivesGui: true,
         matrix: enabled ? enabledMatrix() : disabledMatrix(),
         async execute(invocation) {
             if (!enabled) {
-                return refusal("the ui vector is disabled (`things config set ui-enabled true` to enable it).");
+                return refusal("the ui vector is disabled (`things config set ui-enabled true` to enable it, then " +
+                    "`things helpers setup --gui`).");
             }
             if (invocation.recipe === undefined) {
                 return refusal("ui invocation carried no recipe (compile bug).");
             }
-            return drive(invocation.recipe, tracedRun, aux, budgetMs);
+            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).
-        probeReachability: () => probeSessionReachability(tracedRun, STEP_TIMEOUT_MS),
+        // 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