things-api 0.18.0 → 0.19.1

package/dist/write/vectors/ui.js

@@ -33,6 +33,7 @@ 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 { chordCommand, driveHeadingChordReorder } from "./ui-chord.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;
@@ -72,6 +73,197 @@ const SETTLE_AFTER_REVEAL_MS = 1000;
  */
 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"`;
+/**
+ * The cadence group's re-layout settle budget (BEEP1) — how many times
+ * `set-group-number` re-reads the group's shape looking for two consecutive
+ * identical reads, and how long it waits between reads. ~4s of headroom against
+ * a re-layout measured to finish well inside 1.5s; the gate exits on the FIRST
+ * agreeing pair, so the common (already-settled) case costs one extra read.
+ */
+const SETTLE_READS = 40;
+const SETTLE_POLL_S = 0.1;
+/**
+ * Row tolerance (points) for every LABEL-ANCHORED field address here — how far a
+ * control's y may sit from its label's y and still count as the same row.
+ * Measured on Things 3.23 (CGRD1 §A census): `Every`@286 / interval@283,
+ * `Ends:`@375 / count@372, `days earlier`@413 / start-offset@409 — a 3–4pt
+ * baseline offset, so 8 is ~2× the observed worst case and well under the
+ * ~45pt row pitch of the cadence group.
+ */
+const ROW_TOLERANCE = 8;
+/**
+ * How many of the Next: menu's own item titles a MISS reports back (NEXTPOP1).
+ * A refusal that names only the date the dialog lacked cannot distinguish "the
+ * rule genuinely does not produce that date" from "the menu was not the rule's"
+ * — the two failures read identically, and the second one cost a whole campaign
+ * to tell apart. Naming the pop-up's current value plus the first few options it
+ * offered makes the refusal self-diagnosing. Bounded so a 100-item level cannot
+ * flood the message.
+ */
+const SAMPLE_ITEMS = 5;
+/**
+ * The `Next:` occurrence pop-up's asynchronous-recompute budget (NEXTPOP1) — how
+ * long {@link axSettleOccurrencesScript} waits for the dialog to absorb a rule
+ * change before the drive touches it again, and how often it looks. MEASURED at
+ * **0.4s** on golden-v4 / Things 3.23 (DIAG4: the control flipped from the seed's
+ * first occurrence to the anchor's between t+0.3s and t+0.4s), so the budget is
+ * ~3× the observed latency; the poll exits early the moment the control moves,
+ * which is the only case that costs anything.
+ */
+const OCCURRENCE_SETTLE_MS = 1200;
+const OCCURRENCE_POLL_MS = 100;
+/**
+ * The shared AppleScript handler prelude for every LABEL-ANCHORED field address
+ * in the Repeat dialog — the HXPC1 discrimination law in ONE place, so the
+ * pre-commit audit re-reads each field through the SAME address the drive wrote
+ * it through (a self-referential read-back is exactly what let #589's wrong-field
+ * write report OK).
+ *
+ * The laws, all measured on Things 3.23 / build 32300036 (CGRD1 §A census, and
+ * HXPC1 §A before it — docs/lab/cgrd1-precommit-audit.md, hxpc1-picker-assert.md):
+ *
+ *  - The cadence group's numeric fields are identified by the LABEL ROW they sit
+ *    on, never by index among the group's text fields. Selecting an "Ends: after"
+ *    bound INSERTS the count AHEAD of the interval, so index 1 is a different
+ *    control at different moments.
+ *  - The interval is matched POSITIVELY, on the `Every` label's row. Every fixed
+ *    frequency (daily/weekly/monthly/yearly) carries that label at y=286 with the
+ *    interval at y=283. An AFTER-COMPLETION cadence group carries NEITHER an
+ *    `Every` nor an `Ends:` label (census: its only static text is "after previous
+ *    item is checked off.") and offers exactly ONE text field — so that shape falls
+ *    to the sole-field rule, which is itself a uniqueness check, not an index.
+ *  - Anything else FAILS CLOSED reporting the whole numeric-field inventory rather
+ *    than typing a number into a field it cannot vouch for. An AX tree is an
+ *    undocumented private surface: an unrecognized shape is a refusal, never a
+ *    best guess.
+ */
+const AX_CADENCE_HANDLERS = `on cgLabelY(g, want)
+  tell application "System Events"
+    set outY to missing value
+    repeat with i from 1 to (count of static texts of g)
+      set sv to ""
+      try
+        set sv to (value of static text i of g) as text
+      end try
+      if sv is want then
+        -- bind the position, THEN index it: System Events refuses indexing a
+        -- position read inline from a specifier (-1700).
+        set labelPos to position of static text i of g
+        set outY to item 2 of labelPos
+      end if
+    end repeat
+    return outY
+  end tell
+end cgLabelY
+
+on cgInventory(g)
+  tell application "System Events"
+    set inv to ""
+    repeat with i from 1 to (count of text fields of g)
+      set fp to position of text field i of g
+      set inv to inv & " #" & i & "(y=" & (item 2 of fp) & ",shows=" & ((value of text field i of g) as text) & ")"
+    end repeat
+    if inv is "" then set inv to " (none)"
+    return inv
+  end tell
+end cgInventory
+
+on cgOnRow(g, y, tol, want)
+  tell application "System Events"
+    set hits to {}
+    repeat with i from 1 to (count of text fields of g)
+      set fp to position of text field i of g
+      set dy to (item 2 of fp) - y
+      if dy < 0 then set dy to -dy
+      set onRow to (dy <= tol)
+      if onRow is want then set end of hits to text field i of g
+    end repeat
+    return hits
+  end tell
+end cgOnRow
+
+on cgSettle(g)
+  -- SETTLE ON THE GROUP'S OWN SHAPE, never on a clock (determinism doctrine).
+  -- A frequency switch REBUILDS the cadence group. Two things go wrong when a
+  -- read starts too early: the row discrimination reads positions from controls
+  -- that are still moving, and keystrokes land on a field being torn down —
+  -- unhandled, so macOS beeps (BEEP1). Poll until two consecutive reads of the
+  -- group's label + field-position signature agree, then proceed.
+  tell application "System Events"
+    set sig to ""
+    set prevSig to "<none>"
+    repeat ${SETTLE_READS} times
+      set prevSig to sig
+      set sig to ""
+      repeat with i from 1 to (count of static texts of g)
+        set sv to ""
+        try
+          set sv to (value of static text i of g) as text
+        end try
+        set sig to sig & "|s:" & sv
+      end repeat
+      repeat with i from 1 to (count of text fields of g)
+        set fp to position of text field i of g
+        set sig to sig & "|f:" & (item 2 of fp)
+      end repeat
+      if sig is prevSig then return true
+      delay ${SETTLE_POLL_S}
+    end repeat
+    error "the Repeat dialog's cadence group is still re-laying out — its shape changed on every read; last seen" & sig
+  end tell
+end cgSettle
+
+on cgField(g, target, tol)
+  tell application "System Events"
+    set endsY to my cgLabelY(g, "Ends:")
+    set everyY to my cgLabelY(g, "Every")
+    set nf to (count of text fields of g)
+    if target is "ends-count" then
+      if endsY is missing value then error "the Repeat dialog's cadence group carries no \\"Ends:\\" label, so the ends-after count field cannot be identified — numeric fields:" & my cgInventory(g)
+      set hits to my cgOnRow(g, endsY, tol, true)
+      if (count of hits) is not 1 then error "the Repeat dialog offers " & (count of hits) & " field(s) on the \\"Ends:\\" row, expected exactly 1 — numeric fields:" & my cgInventory(g)
+      return item 1 of hits
+    end if
+    if everyY is not missing value then
+      set hits to my cgOnRow(g, everyY, tol, true)
+      if (count of hits) is not 1 then error "the Repeat dialog offers " & (count of hits) & " field(s) on the \\"Every\\" row, expected exactly 1 — numeric fields:" & my cgInventory(g)
+      return item 1 of hits
+    end if
+    if endsY is not missing value then
+      set hits to my cgOnRow(g, endsY, tol, false)
+      if (count of hits) is not 1 then error "the Repeat dialog offers " & (count of hits) & " field(s) off the \\"Ends:\\" row, expected exactly 1 — numeric fields:" & my cgInventory(g)
+      return item 1 of hits
+    end if
+    if nf is not 1 then error "the Repeat dialog's cadence group carries neither an \\"Every\\" nor an \\"Ends:\\" label and offers " & nf & " numeric field(s), so the interval cannot be identified — numeric fields:" & my cgInventory(g)
+    -- positional-ok: reached ONLY after the line above proved the group holds
+    -- exactly one text field, so this is a uniqueness statement, not an index.
+    -- The after-completion cadence group is that shape (MEASURED, CGRD1 §A: its
+    -- only static text is "after previous item is checked off.", one field).
+    return text field 1 of g
+  end tell
+end cgField
+
+on rfInventory(c)
+  tell application "System Events"
+    set inv to ""
+    repeat with i from 1 to (count of text fields of c)
+      set fp to position of text field i of c
+      set inv to inv & " #" & i & "(y=" & (item 2 of fp) & ",shows=" & ((value of text field i of c) as text) & ")"
+    end repeat
+    if inv is "" then set inv to " (none)"
+    return inv
+  end tell
+end rfInventory
+
+on rfField(c, rowLabel, tol)
+  tell application "System Events"
+    set labelY to my cgLabelY(c, rowLabel)
+    if labelY is missing value then error "the Repeat dialog shows no \\"" & rowLabel & "\\" label, so the field beside it cannot be identified — text fields:" & my rfInventory(c)
+    set hits to my cgOnRow(c, labelY, tol, true)
+    if (count of hits) is not 1 then error "the Repeat dialog offers " & (count of hits) & " field(s) on the \\"" & rowLabel & "\\" row, expected exactly 1 — text fields:" & my rfInventory(c)
+    return item 1 of hits
+  end tell
+end rfField`;
 /** resolve-element: does the element exist right now? Returns "true"/"false". */
 export function axResolveScript(path) {
     return `${SE} to return (exists (${path}))`;
@@ -82,33 +274,49 @@ export function axPressScript(path) {
 }
 /**
  * set-field-value: enter a value into the dialog's numeric text field (interval,
- * ends-count, start-days-earlier). It FOCUSES the field, selects all, TYPES the
- * value, and Tabs to commit — because `set value of <field>` writes the field's
- * displayed text WITHOUT firing the edit, so the app's binding keeps the old
- * number (the field shows "5" but the rule stays interval 1 — a silent no-op
- * exactly like `set value` on a pop-up, UIC6; it went unnoticed while every base
- * case used the default interval 1). Real keystrokes fire the change the binding
- * needs; Tab (not Return, which would fire the default OK button) commits and
- * moves focus. Foreground-bound (keystrokes reach the frontmost app) — the
- * reveal/activate preamble puts Things there. One stable command shape.
+ * ends-count, start-days-earlier) — and into the Move… picker's filter field. It
+ * FOCUSES the field, TYPES the value, and Tabs to commit — because
+ * `set value of <field>` writes the field's displayed text WITHOUT firing the
+ * edit, so the app's binding keeps the old number (the field shows "5" but the
+ * rule stays interval 1 — a silent no-op exactly like `set value` on a pop-up,
+ * UIC6; it went unnoticed while every base case used the default interval 1).
+ * Real keystrokes fire the change the binding needs; Tab (not Return, which would
+ * fire the default OK button) commits and moves focus. Foreground-bound
+ * (keystrokes reach the frontmost app) — the reveal/activate preamble puts Things
+ * there. One stable command shape.
+ *
+ * NO SELECT-ALL KEYSTROKE (BEEP1, 2026-08-25, docs/lab/beep1-numeric-field-beep.md).
+ * The primitive used to send ⌘A before typing, and that ONE keystroke was the
+ * audible macOS alert beep every numeric-field drive fired on the live host:
+ * Things' `Edit ▸ Select All` menu item exists and is DISABLED while the Repeat
+ * sheet is up, AppKit dispatches ⌘A as a menu key equivalent FIRST, the disabled
+ * item swallows it, nothing handles it → NSBeep. It is a menu-dispatch fact, not
+ * a focus race: the beep survives a verified first responder and a 1.5 s settle,
+ * while Tab and the digits themselves are silent. ⌘A was also REDUNDANT —
+ * `set focused of tf to true` installs the field editor with the ENTIRE content
+ * selected (measured: `AXSelectedTextRange` length goes 0 → the full value
+ * length, on both a 1- and a 2-character value), so typing replaces the old value
+ * outright, including the shrinking case (12 → 3) that a stale caret would have
+ * corrupted into "123". Dropping the keystroke is therefore silent AND correct on
+ * all three fields.
+ *
+ * CLOSED-LOOP (determinism doctrine): type, Tab-commit, then READ THE FIELD BACK
+ * and retry if it did not hold — the interval field, when it is the first numeric
+ * field after a frequency/type switch, races the dialog's group re-layout and
+ * reverts to 1 (UIC7, oddities §8l). Re-focus + re-type after a settle lands it
+ * once the re-layout has finished, and the re-focus re-selects the whole value,
+ * so a retry starts from a clean field without ⌘A. Fail-closed (an `error`, i.e.
+ * a transport failure the pipeline re-verifies) if it never holds — the
+ * create/reschedule delta's rule assertion is the final DB-level authority.
  */
 export function axSetValueScript(path, value, attempts = 3) {
     const v = escapeAppleScript(value);
     const n = Math.max(1, Math.trunc(attempts));
-    // CLOSED-LOOP (determinism doctrine): type, Tab-commit, then READ THE FIELD
-    // BACK and retry if it did not hold — the interval field, when it is the first
-    // numeric field after a frequency/type switch, races the dialog's group
-    // re-layout and reverts to 1 (UIC7, oddities §8l). Re-focus + re-type after a
-    // settle lands it once the re-layout has finished. Fail-closed (an `error`,
-    // i.e. a transport failure the pipeline re-verifies) if it never holds — the
-    // create/reschedule delta's rule assertion is the final DB-level authority.
     return `${SE}
   set tf to (${path})
   repeat ${n} times
     set focused of tf to true
     delay 0.15
-    keystroke "a" using command down
-    delay 0.1
     keystroke "${v}"
     delay 0.1
     key code 48
@@ -121,6 +329,309 @@ 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`;
 }
+/**
+ * set-group-number: drive ONE of the Repeat dialog's two numeric fields —
+ * the cadence INTERVAL or the ENDS-AFTER COUNT — addressed by the LABEL ROW it
+ * sits on (HXPC1, docs/lab/hxpc1-picker-assert.md §A; hardened by CGRD1,
+ * docs/lab/cgrd1-precommit-audit.md §A).
+ *
+ * Both fields used to be spelled `text field 1 of group 1`, which is the same
+ * control at different moments. Measured on Things 3.23 (build 32300036):
+ *
+ *   Ends: never   → group text fields = 1  ·  tf1 = interval  @[311,283]
+ *   Ends: after N → group text fields = 2  ·  tf1 = COUNT     @[402,372]
+ *                                             tf2 = interval  @[311,283]
+ *
+ * i.e. selecting the "after" bound INSERTS the count ahead of the interval. The
+ * create path got away with it by driving the interval while it was still the
+ * sole field, but a RESCHEDULE opens the dialog pre-populated: a rule that
+ * already ends after N presents both fields from the first step, so the interval
+ * drive wrote the requested interval into the count field, the count drive then
+ * overwrote it, and the interval silently never changed.
+ *
+ * The addresses are the {@link AX_CADENCE_HANDLERS} laws — POSITIVE label-row
+ * matches wherever the app offers a label to match, a uniqueness check where it
+ * does not, and a fail-closed refusal naming the whole numeric-field inventory
+ * otherwise. The write itself is the {@link axSetValueScript} closed loop —
+ * focus, type, Tab-commit, read back, bounded retries — and, like it, sends NO
+ * select-all keystroke: the ⌘A that used to open it is the macOS alert beep
+ * (BEEP1, docs/lab/beep1-numeric-field-beep.md), and focusing the field already
+ * selects its whole content.
+ *
+ * The read-back this loop performs is SELF-REFERENTIAL by construction — it
+ * re-reads the field it addressed, so it can only prove the keystrokes landed
+ * where they were aimed, never that they were aimed at the right control. The
+ * PRE-COMMIT AUDIT ({@link axAuditDialogScript}) is what closes that: it re-reads
+ * every control through these same handlers just before the OK press.
+ */
+export function axSetGroupNumberScript(groupPath, target, value, attempts = 3, rowTolerance = ROW_TOLERANCE) {
+    const v = escapeAppleScript(value);
+    const n = Math.max(1, Math.trunc(attempts));
+    const tol = Math.max(1, Math.trunc(rowTolerance));
+    return `${AX_CADENCE_HANDLERS}
+
+${SE}
+  set g to (${groupPath})
+  my cgSettle(g)
+  set tf to my cgField(g, "${target}", ${tol})
+  repeat ${n} times
+    set focused of tf to true
+    delay 0.15
+    keystroke "${v}"
+    delay 0.1
+    key code 48
+    delay 0.2
+    try
+      if ((value of tf) as text) is "${v}" then return "OK"
+    end try
+    delay 0.3
+  end repeat
+  error "the ${target} field did not hold value \\"${v}\\" after ${n} attempt(s); last shown: " & ((value of tf) as text)
+end tell`;
+}
+/**
+ * set-row-field: drive a Repeat-dialog text field addressed by the pinned English
+ * LABEL sharing its row — the same discrimination law as
+ * {@link axSetGroupNumberScript}, applied to a field that lives on the dialog
+ * SHELL rather than in the cadence group.
+ *
+ * Its one caller is the "and start [N] days earlier" offset the "Add deadlines"
+ * checkbox reveals, which shipped as `text field 1` of the shell. That address
+ * was the HXPC1 error class exactly: a value-bearing text field picked by index
+ * out of a STATE-DEPENDENT tree (the field does not exist at all until the
+ * checkbox is ticked), verified only by re-reading the same index it wrote. It
+ * happened to be right on 3.23 — measured, the shell carries 0 direct text fields
+ * with deadlines off and exactly 1 with them on, whether or not reminders are also
+ * on (CGRD1 §B census) — but nothing in the address said so, and an AX tree is an
+ * undocumented private surface that may add a second field in any release.
+ *
+ * The label anchor is `days earlier` (y=413 against the field's y=409, CGRD1 §B).
+ * A missing label, or anything other than exactly one field on its row, FAILS
+ * CLOSED naming the shell's whole text-field inventory. The write is the
+ * {@link axSetValueScript} closed loop.
+ */
+export function axSetRowFieldScript(containerPath, rowLabel, value, attempts = 3, rowTolerance = ROW_TOLERANCE) {
+    const v = escapeAppleScript(value);
+    const label = escapeAppleScript(rowLabel);
+    const n = Math.max(1, Math.trunc(attempts));
+    const tol = Math.max(1, Math.trunc(rowTolerance));
+    return `${AX_CADENCE_HANDLERS}
+
+${SE}
+  set c to (${containerPath})
+  set tf to my rfField(c, "${label}", ${tol})
+  repeat ${n} times
+    set focused of tf to true
+    delay 0.15
+    keystroke "${v}"
+    delay 0.1
+    key code 48
+    delay 0.2
+    try
+      if ((value of tf) as text) is "${v}" then return "OK"
+    end try
+    delay 0.3
+  end repeat
+  error "the \\"${label}\\" field did not hold value \\"${v}\\" after ${n} attempt(s); last shown: " & ((value of tf) as text)
+end tell`;
+}
+/** AppleScript list literal of quoted strings. */
+function asList(values) {
+    return `{${values.map((v) => `"${escapeAppleScript(v)}"`).join(", ")}}`;
+}
+/** The intended value(s) as the mismatch report should read them. */
+function intendedText(control) {
+    if (control.expectedLabel !== undefined)
+        return control.expectedLabel;
+    return control.expected.map((v) => `\\"${escapeAppleScript(v)}\\"`).join(" or ");
+}
+/**
+ * audit-dialog: RE-READ EVERY CONTROL THIS DRIVE SET, through each control's own
+ * discriminated address, and refuse to commit if any one of them does not hold
+ * the value the drive intended.
+ *
+ * This exists because a per-step read-back is SELF-REFERENTIAL. Every setter here
+ * confirms its write by re-reading the element it addressed, so it proves the
+ * keystrokes landed where they were aimed — and nothing else. The #589 wrong-field
+ * write reported OK for exactly that reason: the interval drive typed into the
+ * ends-count field, then read the ends-count field back and found its own number
+ * sitting there. The address was wrong; a read-back through the same address
+ * cannot see that.
+ *
+ * The audit is the outside view. It is assembled from the recipe's OWN step list
+ * (so no control the recipe drives can be left out of the audit by omission) and
+ * runs as the last step before the OK press, comparing the dialog's complete
+ * intended state against what the dialog actually shows: frequency, the
+ * after-completion cadence unit, interval, ends bound and its count, the
+ * deadline/reminder checkboxes, the start-days-earlier offset, the weekday set,
+ * the monthly/yearly anchor pop-ups and the 3.23 first-occurrence pop-up. A
+ * mismatch is an `error` naming EVERY differing control with both values, which
+ * aborts the drive fail-closed BEFORE the commit and runs the standard clean-abort
+ * path — nothing reaches the database.
+ *
+ * Deterministic throughout: the cadence group is settled on its own shape
+ * signature (the BEEP1 two-agreeing-reads gate), never on a sleep, and every field
+ * is found by its label row rather than by index ({@link AX_CADENCE_HANDLERS}).
+ *
+ * The dialog's three `AXDateTimeArea` controls are audited separately — their
+ * values are NSDates no System Events read can reach, so they ride
+ * {@link axAuditDateAreasScript} through the same ObjC bridge that writes them.
+ */
+export function axAuditDialogScript(spec, rowTolerance = ROW_TOLERANCE) {
+    const tol = Math.max(1, Math.trunc(rowTolerance));
+    const body = spec.controls
+        .map((c, i) => {
+        const name = escapeAppleScript(c.label);
+        const want = asList(c.expected);
+        const intended = intendedText(c);
+        const miss = `set end of bad to "${name} (intended ${intended}, dialog shows \\"" & v${i} & "\\")"`;
+        switch (c.kind) {
+            case "popup":
+                return `  set v${i} to "(unreadable)"
+  try
+    set v${i} to (value of (${c.path ?? ""})) as text
+  end try
+  if not (my aqAny(v${i}, ${want})) then ${miss}`;
+            case "occurrence-popup":
+                return `  set v${i} to "(unreadable)"
+  try
+    set v${i} to (value of (${c.path ?? ""})) as text
+  end try
+  set d${i} to my aqYMD(v${i})
+  if d${i} is missing value then
+    ${miss}
+  else if not (my aqAny(d${i}, ${want})) then
+    set end of bad to "${name} (intended ${intended}, dialog shows \\"" & v${i} & "\\" = " & d${i} & ")"
+  end if`;
+            case "checkbox":
+                return `  set v${i} to "(unreadable)"
+  try
+    set v${i} to ((value of (${c.path ?? ""})) as integer) as text
+  end try
+  if not (my aqAny(v${i}, ${want})) then set end of bad to "${name} (intended ${intended}, dialog shows " & (my aqTick(v${i})) & ")"`;
+            case "group-number":
+                return `  set v${i} to "(unreadable)"
+  try
+    set v${i} to ((value of (my cgField(g, "${c.numberTarget ?? "interval"}", ${tol}))) as text)
+  end try
+  if not (my aqAny(v${i}, ${want})) then ${miss}`;
+            case "row-field":
+                return `  set v${i} to "(unreadable)"
+  try
+    set v${i} to ((value of (my rfField(sh, "${escapeAppleScript(c.rowLabel ?? "")}", ${tol}))) as text)
+  end try
+  if not (my aqAny(v${i}, ${want})) then ${miss}`;
+            case "weekdays":
+                return `  set got${i} to {}
+  repeat with k from ${Math.max(1, Math.trunc(c.weekdayBase ?? 2))} to (count of pop up buttons of g)
+    set end of got${i} to ((value of pop up button k of g) as text)
+  end repeat
+  set v${i} to my aqJoin(got${i}, ",")
+  set off${i} to false
+  repeat with w in ${want}
+    if not (my aqAny(w as text, got${i})) then set off${i} to true
+  end repeat
+  repeat with w in got${i}
+    if not (my aqAny(w as text, ${want})) then set off${i} to true
+  end repeat
+  if off${i} then ${miss}`;
+        }
+    })
+        .join("\n");
+    return `${AX_CADENCE_HANDLERS}
+
+on aqAny(v, lst)
+  repeat with c in lst
+    if (v as text) is (c as text) then return true
+  end repeat
+  return false
+end aqAny
+
+on aqJoin(lst, sep)
+  set out to ""
+  repeat with x in lst
+    if out is not "" then set out to out & sep
+    set out to out & (x as text)
+  end repeat
+  return out
+end aqJoin
+
+on aqTick(v)
+  if (v as text) is "1" then return "checked"
+  if (v as text) is "0" then return "unchecked"
+  return "\\"" & (v as text) & "\\""
+end aqTick
+
+on aqPad2(n)
+  set s to (n as integer) as text
+  if (length of s) < 2 then set s to "0" & s
+  return s
+end aqPad2
+
+on aqYMD(t)
+  -- Occurrence-pop-up titles are LOCALIZED ("Sun, Jul 12, 2026"), so the match is
+  -- made by PARSING the title to a date and comparing calendar components — never
+  -- by rebuilding the app's display string (the axSelectNextOccurrenceScript law).
+  set s to t as text
+  try
+    set d to date s
+    return ((year of d) as text) & "-" & my aqPad2((month of d) as integer) & "-" & my aqPad2(day of d)
+  end try
+  try
+    set ofs to offset of ", " in s
+    if ofs > 0 then
+      set d to date (text (ofs + 2) thru -1 of s)
+      return ((year of d) as text) & "-" & my aqPad2((month of d) as integer) & "-" & my aqPad2(day of d)
+    end if
+  end try
+  return missing value
+end aqYMD
+
+${SE}
+  set sh to (${spec.shell})
+  set g to (${spec.group})
+  my cgSettle(g)
+  set bad to {}
+${body}
+  if (count of bad) is 0 then return "OK"
+  error "the Repeat dialog does not hold what this drive entered — " & (count of bad) & " control(s) differ: " & my aqJoin(bad, "; ")
+end tell`;
+}
+/**
+ * The pre-commit audit's DATE-AREA leg. The dialog's first-occurrence, ends-on and
+ * reminder controls are `AXDateTimeArea`s whose value is an NSDate — unreachable
+ * from System Events — so they are re-read through the SAME ObjC bridge, the same
+ * shell-scoped walk and the SAME deterministic `pick` discriminator that
+ * {@link axSetDateTimeScript} writes them through. A control the audit cannot find,
+ * or one holding a different date/time, throws naming every area the dialog does
+ * present (y-position + time-of-day), so the drive aborts before the OK press.
+ */
+export function axAuditDateAreasScript(areas) {
+    return `${AX_DATE_AREA_PRELUDE}
+function run(){
+  var apps=$.NSRunningApplication.runningApplicationsWithBundleIdentifier('com.culturedcode.ThingsMac');
+  if(!apps || apps.count===0) throw new Error('Things not running');
+  var app=$.AXUIElementCreateApplication(apps.objectAtIndex(0).processIdentifier);
+  var wanted=${JSON.stringify(areas)};
+  var cal=$.NSCalendar.currentCalendar;
+  var found=[]; try{ var shell=findShell(app); if(shell) collect(shell,'AXDateTimeArea',16,found); }catch(e){ found=[]; }
+  var bad=[];
+  for(var i=0;i<wanted.length;i++){
+    var w=wanted[i];
+    var dt=pick(found,w.target);
+    if(!dt){ bad.push(w.label+' (intended '+w.spec+', but this dialog state presents no '+w.target+' control among ['+inv(found)+'])'); continue; }
+    if(w.spec.indexOf('date:')===0){
+      var got=ymdStr(dt,cal), want=w.spec.slice(5);
+      if(got!==want) bad.push(w.label+' (intended '+want+', dialog shows '+(got||'(no value)')+')');
+    } else {
+      var gott=hmStr(dt,cal), p=w.spec.slice(5).split(':'), wantt=(+p[0])+':'+('0'+(+p[1])).slice(-2);
+      if(gott!==wantt) bad.push(w.label+' (intended '+wantt+', dialog shows '+(gott||'(no value)')+')');
+    }
+  }
+  if(bad.length) throw new Error('the Repeat dialog does not hold what this drive entered — '+bad.length+' control(s) differ: '+bad.join('; '));
+  return 'OK';
+}`;
+}
 /**
  * ensure-checkbox: converge a dialog checkbox to a target state through a
  * DETERMINISTIC CLOSED LOOP (RRD1, determinism doctrine) — never a blind toggle.
@@ -310,6 +821,9 @@ ${SE}
   set theMenu to menu 1 of pu
   set clickedTitle to ""
   set levelsSeen to 0
+  set opener to (value of pu) as text
+  set sample to ""
+  set sampled to 0
   if isToday then
     set nms to name of every menu item of theMenu
     if (count of nms) > 0 then
@@ -330,6 +844,13 @@ ${SE}
     repeat with i from 1 to (count of nms)
       set nm to item i of nms
       if nm is not missing value then
+        -- Keep a short sample of what THIS menu actually offered, so a miss can
+        -- report the dates the dialog had rather than only the one it lacked.
+        if sampled < ${SAMPLE_ITEMS} then
+          if sample is not "" then set sample to sample & ", "
+          set sample to sample & (nm as text)
+          set sampled to sampled + 1
+        end if
         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
@@ -363,7 +884,7 @@ ${SE}
   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."
+    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, which opened on \\"" & opener & "\\" and led with: " & sample & ". 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
@@ -373,6 +894,48 @@ ${SE}
   return "OK"
 end tell`;
 }
+/**
+ * settle-occurrences: let the 3.23 `Next:` pop-up ABSORB the rule change the
+ * preceding steps made, before the drive touches the dialog again (NEXTPOP1).
+ *
+ * MEASURED (golden-v4 / Things 3.23, `research-nextpop1.sh` DIAG3/DIAG4): the
+ * dialog recomputes the first-occurrence pop-up — its displayed value AND the
+ * menu of occurrences behind it — ASYNCHRONOUSLY. After the yearly anchor was
+ * moved from Aug 6 to Aug 20 the control flipped at **t+0.4s** with nothing else
+ * driven; when the very next step (the "Add deadlines" checkbox) was pressed
+ * inside that window instead, the control NEVER caught up — it still read
+ * `Thu, Aug 6, 2026`, and its menu still enumerated the Aug-6 series, six
+ * seconds later. A cancelled recompute does not retry.
+ *
+ * That is what made every deadlined monthly/yearly promote fail closed on 3.23:
+ * the anchor drive is followed immediately by the deadline controls, so by the
+ * time `select-next-occurrence` opened the menu it was the SEED's series, and
+ * the requested date — the rule's own first due date — was genuinely not in it
+ * (VMRES1 §4.3, reproduced and explained in NEXTPOP1).
+ *
+ * The wait is closed-loop in the direction that matters: it exits the moment the
+ * control MOVES, which is the case that needs waiting for. When the rule change
+ * did not move the first occurrence there is nothing to observe, so the budget
+ * bounds it — deliberately over-cautious, since the cost is a fraction of a
+ * second and the alternative is a series that starts on the wrong date.
+ */
+export function axSettleOccurrencesScript(popupPath, budgetMs = OCCURRENCE_SETTLE_MS, pollMs = OCCURRENCE_POLL_MS) {
+    const poll = Math.max(50, Math.trunc(pollMs)) / 1000;
+    const reads = Math.max(1, Math.ceil(Math.max(1, Math.trunc(budgetMs)) / Math.max(50, pollMs)));
+    // `before` and `after` are AppleScript's own positional keywords and `now` is
+    // taken too — `set before to …` does not even COMPILE (osacompile: "Expected
+    // expression but found “to”"), and osascript reports that as a drive failure at
+    // run time, mid-dialog. Hence the deliberately dull variable names.
+    return `${SE}
+  set wasValue to (value of ${popupPath}) as text
+  repeat ${reads} times
+    delay ${poll}
+    set curValue to (value of ${popupPath}) as text
+    if curValue is not wasValue then return "moved: " & wasValue & " -> " & curValue
+  end repeat
+  return "unchanged: " & wasValue
+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).
@@ -473,6 +1036,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
@@ -488,9 +1064,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
@@ -583,6 +1162,141 @@ export function axKeyScript(keys) {
         : `keystroke "${escapeAppleScript(k)}"`);
     return `tell application "System Events" to tell process "Things3"\n  ${lines.join("\n  ")}\nend tell`;
 }
+/**
+ * type-text: send literal text to whatever control holds focus (HXPC1). The
+ * Move… picker focuses its own filter field the instant it opens, and that field
+ * is NOT addressable as a direct child of the picker window — so there is no
+ * element to hand `set-value`, whose select-all + Tab commit would be wrong for a
+ * search field regardless (a popover filter has no next key view for Tab to move
+ * to). Unlike {@link axKeyScript}, which splits its spec on whitespace and would
+ * drop the spaces out of a multi-word project title, this sends the string as
+ * ONE keystroke. It is deliberately not self-verifying: the `click-picker-row`
+ * step that follows resolves the destination row by name and fails closed when
+ * the filter did not produce it, so a keystroke that landed elsewhere can never
+ * be committed. One stable command shape.
+ */
+export function axTypeTextScript(text) {
+    return `${SE}
+  keystroke "${escapeAppleScript(text)}"
+end tell`;
+}
+/**
+ * resolve-frame for a control nested inside a CONTENT-TABLE ROW: walk the
+ * table's rows → cells → cell children and return the frame of the one whose
+ * `AXDescription` equals `description` (HXPC1, docs/lab/hxpc1-picker-assert.md
+ * §B0). Same "x y w h" contract as {@link axFrameScript}.
+ *
+ * This exists because the heading row's `…` button — the only content-row
+ * control that carries its own title (`"More. <heading title>"`, the HEADXPROJ
+ * enabler) — sits at `UI element N of cell 1 of row M of the table`, and
+ * `first UI element of <table> whose description is …` searches the table's
+ * DIRECT children only. Those are the rows, which carry no description, so the
+ * shipped one-level spelling matched nothing and the ellipsis drives
+ * (`project.move-heading-to-project`, `project.dissolve-heading`) died at their
+ * own frame resolution before any click — measured on Things 3.23 against a
+ * heading whose button the raw Accessibility API resolves at the same instant.
+ * The row/cell indices are never guessed: every row is walked and the match is
+ * exact, so a heading whose title changed under us fails closed by name.
+ */
+export function axRowCellFrameScript(tablePath, description) {
+    const d = escapeAppleScript(description);
+    return `${SE}
+  set t to (${tablePath})
+  repeat with r in rows of t
+    repeat with c in UI elements of r
+      repeat with e in UI elements of c
+        try
+          if ((description of e) as text) is "${d}" then
+            set _p to position of e
+            set _s to size of e
+            return ((item 1 of _p) as text) & " " & ((item 2 of _p) as text) & " " & ((item 1 of _s) as text) & " " & ((item 2 of _s) as text)
+          end if
+        end try
+      end repeat
+    end repeat
+  end repeat
+  error "no row of this project's list exposes \\"${d}\\" — the heading may have been renamed, moved or deleted since it was read"
+end tell`;
+}
+/**
+ * resolve-frame for the Move… picker ROW carrying an exact project title — the
+ * step that replaced the recipe's blind Return (HXPC1,
+ * docs/lab/hxpc1-picker-assert.md §B).
+ *
+ * The picker exposes no `AXSelected` / `AXFocused` / `AXHighlighted` on any row
+ * (measured — only its filter field is focused), so there is nothing to read
+ * back from a keyboard commit and no way to assert what Return would take. What
+ * it does expose is one `AXUnknown` per row whose `AXDescription` IS the project
+ * title, and — whenever the filter holds text — a trailing
+ * `New Project "<typed text>"` row that CREATES a project when committed. That
+ * row is what the blind Return took whenever the destination was missing from
+ * the picker, which an ordinary database-resolved destination reaches: a
+ * COMPLETED or CANCELED project appears nowhere in the picker, so the drive
+ * minted a second project of the same title and moved the heading into it
+ * (measured 3.23: projects 14 → 15, heading re-parented to the new row).
+ *
+ * So the commit is addressed instead of guessed. The script requires:
+ *   - the picker to be the window it claims (its `AXIdentifier` begins
+ *     `MovePopUpDialog-`) — a positive identity check, so a different detached
+ *     window can never be clicked into;
+ *   - EXACTLY ONE row whose description equals the destination title (the
+ *     New-Project row's description is the quoted form, so an exact match cannot
+ *     hit it);
+ *   - that row's centre to lie inside the picker's own scroll area — the CNCAC1
+ *     off-screen hazard, where a row scrolled past the fold still resolves a
+ *     frame and a click at it lands on the desktop.
+ * Any miss FAILS CLOSED naming the destination and listing every row the picker
+ * actually offered, so the caller learns what the app was willing to move to.
+ */
+export function axPickerRowFrameScript(pickerPath, title) {
+    const t = escapeAppleScript(title);
+    return `${SE}
+  set w to (${pickerPath})
+  set pickerId to ""
+  try
+    set pickerId to (value of attribute "AXIdentifier" of w) as text
+  end try
+  if pickerId does not start with "MovePopUpDialog-" then
+    error "the front dialog is not the Move… project picker (window id \\"" & pickerId & "\\") — nothing was committed"
+  end if
+  -- positional-ok: the picker window holds exactly one scroll area (MEASURED,
+  -- HXPC1 §B2: "direct text fields=0  scroll areas=1"), and the window's own
+  -- AXIdentifier was checked above, so this is a container handle inside an
+  -- already-identified window — the ROW is addressed by exact title below.
+  set sa to scroll area 1 of w
+  set saPos to position of sa
+  set saSize to size of sa
+  set saTop to item 2 of saPos
+  set saBottom to saTop + (item 2 of saSize)
+  set hits to {}
+  set offered to ""
+  repeat with i from 1 to (count of UI elements of sa)
+    set e to UI element i of sa
+    set d to ""
+    try
+      set d to (description of e) as text
+    end try
+    if d is not "" and (role of e) is "AXUnknown" then
+      set offered to offered & " [" & d & "]"
+      if d is "${t}" then set end of hits to e
+    end if
+  end repeat
+  if (count of hits) is 0 then
+    error "the Move… picker offers no project named \\"${t}\\" — it offered:" & offered & ". Committing here would have created a new project with that name instead of moving into the existing one. A completed or canceled project is not offered by this picker."
+  end if
+  if (count of hits) > 1 then
+    error "the Move… picker offers " & (count of hits) & " rows named \\"${t}\\" — it offered:" & offered
+  end if
+  set row1 to item 1 of hits
+  set rp to position of row1
+  set rs to size of row1
+  set cy to (item 2 of rp) + ((item 2 of rs) / 2)
+  if cy < saTop or cy > saBottom then
+    error "the \\"${t}\\" row is scrolled out of the Move… picker's visible list, so clicking it would land outside the picker — narrow the destination or scroll it into view"
+  end if
+  return ((item 1 of rp) as text) & " " & ((item 2 of rp) as text) & " " & ((item 1 of rs) as text) & " " & ((item 2 of rs) as text)
+end tell`;
+}
 /** The abort keystroke sent to dismiss a half-open sheet/popover on failure. */
 export function axAbortScript() {
     return `tell application "System Events" to key code 53`; // Escape
@@ -603,6 +1317,9 @@ export function axAbortScript() {
 export function axCloseReopenActivateScript() {
     return `tell application "Things3"
   try
+    -- positional-ok: an APP-LEVEL command to the Things scripting dictionary, not
+    -- an Accessibility element path — "close the front window", whichever it is,
+    -- which is the whole intent of the maneuver (a stuck sheet goes with it).
     close window 1
   end try
   reopen
@@ -624,6 +1341,8 @@ export function axSheetOpenScript() {
     return `${SE}
   set sheetOpen to false
   try
+    -- positional-ok: an EXISTENCE probe over the one attached sheet a window can
+    -- present; no element is read or written through this path.
     if (exists sheet 1 of (first window whose subrole is "AXStandardWindow")) then set sheetOpen to true
   end try
   try
@@ -791,45 +1510,7 @@ function clickPointCommand(x, y, label) {
  * calendar date at midnight). One stable JXA shape.
  */
 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 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); }
+    return `${AX_DATE_AREA_PRELUDE}
 function run(){
   var apps=$.NSRunningApplication.runningApplicationsWithBundleIdentifier('com.culturedcode.ThingsMac');
   if(!apps || apps.count===0) throw new Error('Things not running');
@@ -867,7 +1548,9 @@ function run(){
   $.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).
+  // rather than let a garbled commit verify as ok (YANCH1 #493). Like every
+  // per-step read-back here it is SELF-REFERENTIAL (it re-reads the area it just
+  // picked), so the pre-commit audit re-checks it from the outside.
   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');
@@ -878,6 +1561,55 @@ function run(){
   return 'OK';
 }`;
 }
+/**
+ * The shared ObjC-bridge prelude for every `AXDateTimeArea` read or write: the
+ * attribute helpers, the DIALOG-SHELL resolver (so the walk stays inside the
+ * dialog's small subtree — the app-root descent PERF2 removed cost ~4.4s on a busy
+ * host), and the deterministic {@link pick} target discriminator. The write
+ * ({@link axSetDateTimeScript}) and the pre-commit read
+ * ({@link axAuditDateAreasScript}) MUST agree on which area is which, so they
+ * share one definition rather than two that can drift apart.
+ */
+const AX_DATE_AREA_PRELUDE = `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 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); }
+`;
 /**
  * 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
@@ -1035,6 +1767,33 @@ export function commandForStep(step, targetUuid) {
                 label: step.label,
                 script: axSetValueScript(step.path ?? "", step.value ?? ""),
             };
+        case "set-group-number":
+            return {
+                primitive: "set-group-number",
+                label: step.label,
+                script: axSetGroupNumberScript(step.path ?? "", step.numberTarget ?? "interval", step.value ?? ""),
+            };
+        case "set-row-field":
+            return {
+                primitive: "set-row-field",
+                label: step.label,
+                script: axSetRowFieldScript(step.path ?? "", step.rowLabel ?? "", step.value ?? ""),
+            };
+        case "audit-dialog":
+            // Compiled by driveDialogAudit, which resolves the live dialog shell and the
+            // measured shape first (a control's path and its weekday base both depend on
+            // them). This shape exists only so the step renders/compiles uniformly.
+            return {
+                primitive: "audit-dialog",
+                label: step.label,
+                script: "",
+            };
+        case "type-text":
+            return {
+                primitive: "type-text",
+                label: step.label,
+                script: axTypeTextScript(step.value ?? ""),
+            };
         case "select-popup":
             return {
                 primitive: "select-popup",
@@ -1068,6 +1827,12 @@ export function commandForStep(step, targetUuid) {
                 label: step.label,
                 script: axSelectNextOccurrenceScript(step.path ?? "", step.value ?? ""),
             };
+        case "settle-occurrences":
+            return {
+                primitive: "settle-occurrences",
+                label: step.label,
+                script: axSettleOccurrencesScript(step.path ?? ""),
+            };
         case "converge-weekdays":
             return {
                 primitive: "converge-weekdays",
@@ -1101,11 +1866,26 @@ export function commandForStep(step, targetUuid) {
         case "click-element":
             // Phase 1 of the click: read the target's frame. driveClickElement runs
             // this, then posts the click at the resolved center and asserts the outcome.
+            // A `rowCellDescription` step resolves its target by walking the addressed
+            // content table's rows/cells instead (the heading `…` button, which sits
+            // three levels below the table a `whose` clause can reach).
             return {
                 primitive: "resolve-frame",
                 label: step.label,
                 lang: "applescript",
-                script: axFrameScript(step.path ?? ""),
+                script: step.rowCellDescription !== undefined
+                    ? axRowCellFrameScript(step.path ?? "", step.rowCellDescription)
+                    : axFrameScript(step.path ?? ""),
+            };
+        case "click-picker-row":
+            // Phase 1 of the picker commit: resolve the row carrying the destination's
+            // exact title (identity-checked, uniqueness-checked, on-screen-checked).
+            // driveClickElement then clicks it — the recipe never presses Return.
+            return {
+                primitive: "resolve-frame",
+                label: step.label,
+                lang: "applescript",
+                script: axPickerRowFrameScript(step.path ?? "", step.value ?? ""),
             };
         case "drag-reorder":
             // Composite step: drive() hands it to the sidebar drag driver, which
@@ -1117,8 +1897,32 @@ export function commandForStep(step, targetUuid) {
                 lang: "javascript",
                 script: jxaSidebarSnapshotScript(),
             };
+        case "chord-reorder":
+            // Composite step: drive() hands it to the heading-chord driver, which
+            // dispatches its own select/chord commands through `run` and asserts the
+            // database between them. This shape only exists so the step renders and
+            // compiles uniformly; the chord it names is the FIRST hop's, and the
+            // driver recomputes every subsequent one from the live order.
+            return chordCommand("up-one");
     }
 }
+/**
+ * Recover the message an AppleScript `error "…"` raised from osascript's stderr,
+ * dropping the wrapper osascript adds around it (`<line>:<col>: execution error:
+ * <message> (-1728)`). Returns null when stderr carries no such message, so a
+ * caller can fall back to its own wording. This is what lets a resolver script
+ * REFUSE with a sentence the operator can act on — "the Move… picker offers no
+ * project named X — it offered […]" — instead of the driver's generic guess.
+ */
+function scriptErrorText(stderr) {
+    const raw = stderr.trim();
+    if (raw === "")
+        return null;
+    const marker = raw.lastIndexOf("execution error:");
+    const body = marker >= 0 ? raw.slice(marker + "execution error:".length) : raw;
+    const trimmed = body.replace(/\s*\(-?\d+\)\s*$/, "").trim();
+    return trimmed === "" ? null : trimmed;
+}
 /**
  * Execute a `click-element` step: resolve the target's AX frame, synthesize a
  * mouse click at its center, then verify the declared post-click outcome. Fails
@@ -1130,10 +1934,17 @@ async function driveClickElement(step, run) {
     const frameRes = await run(commandForStep(step, ""), STEP_TIMEOUT_MS);
     const center = frameRes.ok ? parseFrameCenter(frameRes.stdout) : null;
     if (center === null) {
+        // A resolver that REFUSED (rather than merely failing to find an element)
+        // carries the diagnosis — which row it wanted, and what the surface offered
+        // instead. Prefer it over the generic guess: that text is the whole point of
+        // the picker-row and heading-button resolvers (HXPC1).
+        const named = scriptErrorText(frameRes.stderr);
         return {
             ok: false,
-            why: "its on-screen position did not resolve — a Things update may have moved the control, " +
-                "or the app is not in the expected state; no click was sent",
+            why: named !== null
+                ? `${named} — no click was sent`
+                : "its on-screen position did not resolve — a Things update may have moved the control, " +
+                    "or the app is not in the expected state; no click was sent",
         };
     }
     const clickRes = await run(clickPointCommand(center.x, center.y, step.label), STEP_TIMEOUT_MS);
@@ -1162,6 +1973,121 @@ async function driveClickElement(step, run) {
     }
     return { ok: true };
 }
+/**
+ * Execute the PRE-COMMIT FULL-DIALOG AUDIT step (CGRD1): re-read every control the
+ * drive set — through each control's own discriminated address — and refuse the
+ * commit if any of them does not hold the intended value.
+ *
+ * Three resolutions happen here rather than in the recipe, because only the driver
+ * knows them: WHICH dialog shell is live (attached sheet vs detached editor), which
+ * SHAPE the dialog measured (the +1 group-index fork, and which first-occurrence
+ * control class exists), and therefore which candidate path each control has. A
+ * shell that does not resolve, or a shape-dependent control with no shape probed,
+ * fails closed exactly like every other address here — an unaudited commit is not
+ * an option, because the audit is the only non-self-referential check the drive has.
+ *
+ * The System Events sweep and the ObjC date-area sweep are separate commands
+ * because the dialog's date/time controls hold NSDates that System Events cannot
+ * read; both must pass.
+ */
+async function driveDialogAudit(step, run, dialogShape) {
+    const plan = step.audit;
+    if (plan === undefined)
+        return { ok: false, why: "no audit plan compiled (recipe bug)" };
+    // Which of the two dialog shells is live, in the SAME priority order the drive's
+    // own candidate resolution used — so the audit reads the dialog the drive wrote.
+    let shellIndex = -1;
+    for (let i = 0; i < plan.shells.length; i += 1) {
+        const res = await run({
+            primitive: "resolve",
+            label: step.label,
+            script: axResolveScript(plan.shells[i]),
+        }, STEP_TIMEOUT_MS);
+        if (res.ok && res.stdout.trim() === "true") {
+            shellIndex = i;
+            break;
+        }
+    }
+    if (shellIndex < 0) {
+        return {
+            ok: false,
+            why: "the Repeat dialog could not be re-read before committing (neither the attached sheet " +
+                "nor the detached repeat editor window resolved), so what it holds could not be checked",
+        };
+    }
+    const shell = plan.shells[shellIndex];
+    const group = (plan.groups[shellIndex] ?? plan.groups[0]);
+    const scriptControls = [];
+    const dateAreas = [];
+    for (const raw of plan.controls) {
+        if (raw.onlyShape !== undefined || raw.shaped !== undefined) {
+            if (dialogShape === null)
+                return { ok: false, why: SHAPE_UNPROBED };
+            if (raw.onlyShape !== undefined && raw.onlyShape !== dialogShape)
+                continue;
+        }
+        const override = raw.shaped === undefined ? undefined : raw.shaped[dialogShape ?? "next-popup"];
+        if (raw.shaped !== undefined && override === undefined) {
+            return {
+                ok: false,
+                why: `the audit has no check for "${raw.label}" under the "${dialogShape ?? "unmeasured"}" Repeat dialog (recipe bug)`,
+            };
+        }
+        const control = { ...raw, ...override };
+        if (control.kind === "date-area") {
+            dateAreas.push({
+                label: control.label,
+                target: control.dtTarget ?? "next",
+                spec: control.dtSpec ?? "",
+            });
+            continue;
+        }
+        const candidates = control.pathCandidates;
+        scriptControls.push({
+            label: control.label,
+            kind: control.kind,
+            ...(candidates !== undefined && {
+                path: (candidates[shellIndex] ?? candidates[0]),
+            }),
+            ...(control.numberTarget !== undefined && { numberTarget: control.numberTarget }),
+            ...(control.rowLabel !== undefined && { rowLabel: control.rowLabel }),
+            ...(control.weekdayBase !== undefined && { weekdayBase: control.weekdayBase }),
+            expected: control.expected ?? [],
+            ...(control.expectedLabel !== undefined && { expectedLabel: control.expectedLabel }),
+        });
+    }
+    if (scriptControls.length > 0) {
+        const res = await run({
+            primitive: "audit-dialog",
+            label: step.label,
+            script: axAuditDialogScript({ shell, group, controls: scriptControls }),
+        }, STEP_TIMEOUT_MS);
+        if (!res.ok || res.stdout.trim() !== "OK") {
+            return { ok: false, why: auditFailureText(res) };
+        }
+    }
+    if (dateAreas.length > 0) {
+        const res = await run({
+            primitive: "audit-dialog",
+            label: step.label,
+            lang: "javascript",
+            script: axAuditDateAreasScript(dateAreas),
+        }, STEP_TIMEOUT_MS);
+        if (!res.ok || res.stdout.trim() !== "OK") {
+            return { ok: false, why: auditFailureText(res) };
+        }
+    }
+    return { ok: true };
+}
+/** The audit's own refusal text, preferred over the driver's generic guess. */
+function auditFailureText(res) {
+    const named = scriptErrorText(res.stderr);
+    if (named !== null)
+        return `${named} — nothing was committed`;
+    if (res.timedOut === true)
+        return "the pre-commit dialog audit timed out; nothing was committed";
+    return "the Repeat dialog could not be re-read before committing; nothing was committed";
+}
 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
@@ -1210,7 +2136,14 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS, re
     // `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
             ? ""
@@ -1225,7 +2158,28 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS, re
                     : " 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…"
@@ -1239,7 +2193,7 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS, re
         // 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;
@@ -1354,6 +2308,21 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS, re
             done.push(`${step.label} (${outcome.detail})`);
             continue;
         }
+        if (step.primitive === "chord-reorder") {
+            // The heading-chord driver runs its own select → chord → DB-assert loop
+            // (ui-chord.ts): every chord is computed from the order it just read, and
+            // a chord that moves nothing (or moves the wrong row) stops the drive
+            // rather than being re-sent. No sheet is involved, so no dismissal clause.
+            if (step.chord === undefined)
+                return partial(step.label, "no chord spec compiled");
+            const spec = step.chord;
+            // the chord ladder depends on the UI state the reveal produced
+            const outcome = await driveHeadingChordReorder(spec, run, aux.headingOrder, (ordinal) => axSelectHeadingRowScript(spec.tablePath, ordinal));
+            if (!outcome.ok)
+                return partial(step.label, outcome.detail);
+            done.push(`${step.label} (${outcome.detail})`);
+            continue;
+        }
         // Resolve a candidate-addressed step's effective element before dispatch
         // (the sheet-vs-detached-window disjunction). A miss fails closed.
         if (step.pathCandidates !== undefined) {
@@ -1384,7 +2353,7 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS, re
                         "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.stderr.trim() || "the dialog-shape probe failed", clear, res.timedOut === true);
             }
             dialogShape = verdict;
             done.push(`${step.label} (${verdict})`);
@@ -1408,7 +2377,7 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS, re
                     ? 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;
@@ -1430,14 +2399,31 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS, re
                         : "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;
+        }
+        if (step.primitive === "audit-dialog") {
+            // The last thing before the commit: re-read EVERY control this drive set,
+            // through each control's own discriminated address, and abort fail-closed if
+            // any of them disagrees with what was requested (CGRD1). Every per-step
+            // read-back before this point is self-referential — it re-reads the element it
+            // addressed — so a wrong ADDRESS is invisible until here. A mismatch clears
+            // the dialog through the standard clean-abort path, so nothing is committed.
+            const outcome = await driveDialogAudit(step, run, dialogShape);
+            if (!outcome.ok) {
+                const clear = await clearDialog(run);
+                return partial(step.label, outcome.why ?? "the pre-commit dialog audit failed", clear);
             }
             done.push(step.label);
             continue;
         }
-        if (step.primitive === "click-element") {
+        if (step.primitive === "click-element" || step.primitive === "click-picker-row") {
             // A mouse click at an AX-resolved frame center (the NATIVE1 primitive),
-            // used only where AXPress is inert (Things' custom `…`/repeat-bar popover).
+            // used only where AXPress is inert (Things' custom `…`/repeat-bar popover)
+            // — and, for `click-picker-row`, where committing by keyboard would take
+            // whatever the app highlighted, including the row that CREATES a project.
             // the click depends on the UI state the previous step produced
             const outcome = await driveClickElement(step, run);
             if (!outcome.ok) {
@@ -1456,7 +2442,7 @@ async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS, re
             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);
     }
@@ -1527,8 +2513,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;
@@ -1554,10 +2541,14 @@ export function createUiVector(config, run = defaultRun, aux = {}) {
     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).");