things-api 0.15.0 → 0.17.0

package/dist/write/vectors/ui.js

@@ -26,8 +26,11 @@
  * v1 shells out to `osascript` with ONE stable command shape per primitive.
  */
 import { execFile } from "node:child_process";
+import { DEFAULT_UI_DRIVE_BUDGET_MS } from "../../config.js";
+import { 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 { certificationOf } from "./ui-certification.js";
 import { driveSidebarAreaReorder, jxaSidebarSnapshotScript } from "./ui-drag.js";
 /** GUI driving can stall on an unanswered sheet; give each step headroom. */
@@ -98,6 +101,39 @@ export function axSetValueScript(path, value, attempts = 3) {
   error "field did not hold value \\"${v}\\" after ${n} attempt(s); last shown: " & ((value of tf) as text)
 end tell`;
 }
+/**
+ * ensure-checkbox: converge a dialog checkbox to a target state through a
+ * DETERMINISTIC CLOSED LOOP (RRD1, determinism doctrine) — never a blind toggle.
+ * It reads the checkbox's `AXValue` (0 = unchecked, 1 = checked), presses it ONLY
+ * when the observed value differs from `target`, then RE-READS to confirm the new
+ * value equals `target`. A press that did not register (or a value that has not
+ * settled) is retried a bounded number of times; if it never converges the script
+ * FAILS CLOSED (an `error`, i.e. a transport failure the pipeline re-verifies).
+ *
+ * This is what makes the "Add deadlines" / "Add reminders" checkboxes safe on a
+ * PRE-POPULATED reschedule dialog: the dialog opens with the item's CURRENT
+ * deadline/reminder state already ticked, so the old unconditional `click`
+ * FLIPPED an already-correct box the wrong way — the live #493-adjacent bug where
+ * a blind "Add deadlines" press UNCHECKED an already-deadlined rule and hid the
+ * "start N days earlier" field, collapsing the drive. Reading before pressing
+ * makes an already-correct box a no-op. One stable command shape per primitive.
+ */
+export function axEnsureCheckboxScript(path, target, attempts = 3) {
+    const want = target ? 1 : 0;
+    const n = Math.max(1, Math.trunc(attempts));
+    return `${SE}
+  set cb to (${path})
+  repeat ${n} times
+    set cur to (value of cb) as integer
+    if cur is ${want} then return "OK"
+    click cb
+    delay 0.2
+  end repeat
+  set cur to (value of cb) as integer
+  if cur is ${want} then return "OK"
+  error "checkbox did not converge to ${want} after ${n} attempt(s); still " & cur
+end tell`;
+}
 /**
  * select-popup: choose an item in a pop-up button by NAME. Setting `value` on a
  * Things pop-up button is a silent no-op (UIC1 / UI2-i) — the control must be
@@ -213,6 +249,41 @@ export function axSelectHeadingRowScript(tablePath, ordinal) {
 end tell
 return "NOMATCH"`;
 }
+/**
+ * assert-eligible: after a `things:///show?id=` reveal, VERIFY the target to-do
+ * is genuinely the sole selection AND that the menu item that acts on it is
+ * enabled — before the menu is pressed (ADR1, issue #480). The reveal is assumed
+ * to select the row, but on some surfaces it can navigate without selecting; an
+ * AXPress on the resulting DISABLED `Items ▸ Repeat…` is a silent no-op, so the
+ * dialog never opens and the drive dies far downstream at the dialog-wait timeout
+ * with no hint of the real cause. Reading `Things3 → id of selected to dos` is
+ * uuid-precise (never a fuzzy title match), so a match GUARANTEES the intended row
+ * is selected. Returns "OK" only when exactly the target is selected and the menu
+ * item is enabled; otherwise a diagnostic (`NOTSEL…`/`WRONGSEL…`/`DISABLED…`)
+ * naming expected vs observed. Pure System Events + Things scripting, background-
+ * capable. One stable command shape per primitive.
+ */
+export function axAssertEligibleScript(targetUuid, menuItemPath) {
+    const u = escapeAppleScript(targetUuid);
+    return `set selIds to {}
+tell application "Things3"
+  try
+    set selIds to id of selected to dos
+  end try
+end tell
+if (count of selIds) is 0 then return "NOTSEL no to-do is selected after the reveal (expected ${u}) — the show URL navigated without selecting an eligible row"
+if (count of selIds) is greater than 1 then return "NOTSEL " & (count of selIds) & " to-dos are selected, expected exactly the target ${u}"
+set theId to (item 1 of selIds) as text
+if theId is not "${u}" then return "WRONGSEL the selected to-do is " & theId & ", expected the target ${u}"
+set repEnabled to false
+tell application "System Events" to tell process "Things3"
+  try
+    set repEnabled to enabled of ${menuItemPath}
+  end try
+end tell
+if repEnabled is false then return "DISABLED the target ${u} is selected but its Repeat menu item is disabled (not an eligible row for this action)"
+return "OK"`;
+}
 /** activate: foreground Things (the fallback preamble step). */
 export function axActivateScript() {
     return `tell application "Things3" to activate`;
@@ -232,6 +303,29 @@ export function axKeyScript(keys) {
 export function axAbortScript() {
     return `tell application "System Events" to key code 53`; // Escape
 }
+/**
+ * The PROVEN app-level clearance / relocation maneuver (SESSGATE, #480, live-host
+ * recovery): close the front Things window — which takes an attached modal sheet
+ * with it — then reopen and activate. Runs entirely through Things' own
+ * AppleScript dictionary, so it works WITHOUT the Accessibility tree (the exact
+ * property needed when the session is AX-blind). Two uses:
+ *   - CLEANUP: clear a stuck modal sheet a failed drive left open (unblocks the
+ *     app-wide AppleScript-mutation freeze that sheet imposes);
+ *   - RELOCATION: pull a window that was on another Space back to the current one
+ *     so its dialog can open AX-reachably (the wrong-Space recovery branch).
+ * `reopen` restores the default window on the CURRENT Space; `activate` foregrounds
+ * it. Returns "OK".
+ */
+export function axCloseReopenActivateScript() {
+    return `tell application "Things3"
+  try
+    close window 1
+  end try
+  reopen
+  activate
+end tell
+return "OK"`;
+}
 /**
  * sheet-open probe: is a modal SHEET attached to the Things standard window, OR
  * a detached repeat-editor / popover window (an `AXUnknown` that is not the
@@ -262,19 +356,80 @@ async function sheetStillOpen(run) {
     return !(res.ok && res.stdout.trim() === "false");
 }
 /**
- * Send Escape and VERIFY the sheet/popover is gone (0½ defect (d): the abort
- * must never claim dismissal it did not confirm). Retries Escape ONCE if the
- * first is not honored. Returns whether dismissal was verified — the caller
- * words its partial-state report accordingly (fail-closed: on an unverifiable
- * dismissal it must warn the sheet may remain open).
+ * Clear a half-open sheet/popover a failed drive left behind — HONESTLY (SESSGATE
+ * #480 fix; supersedes the old verifiedAbort, whose AX-blind sheet probe returned
+ * "gone" it could not actually see, letting the still-open modal freeze the
+ * app-wide AppleScript mutations the caller then attempted — the auto-trash
+ * silent-noop). Escape first; then:
+ *   - AX-BLIND (a not-reachable probe): Escape may never have reached the sheet
+ *     and the sheet probe cannot see it, so run the app-level close+reopen that
+ *     works blind (it takes the stuck sheet with the window). Reported as
+ *     "cleared-blind" — never falsely "confirmed gone".
+ *   - REACHABLE: the sheet probe is trustworthy — confirm the dismissal (retry
+ *     Escape once), and if it will not go, warn "may remain".
  */
-async function verifiedAbort(run) {
+async function clearDialog(run) {
     const escape = () => run({ primitive: "key", label: "abort (Escape)", script: axAbortScript() }, STEP_TIMEOUT_MS);
     await escape();
+    const reach = await probeSessionReachability(run, STEP_TIMEOUT_MS);
+    if (!reach.reachable) {
+        // Cannot trust Escape or the sheet probe while AX-blind — use the proven
+        // app-level maneuver, which clears a stuck sheet without the Accessibility tree.
+        await run({
+            primitive: "resolve",
+            label: "clear a stuck dialog (close the Things window and reopen it)",
+            script: axCloseReopenActivateScript(),
+        }, STEP_TIMEOUT_MS);
+        return { state: "cleared-blind" };
+    }
     if (!(await sheetStillOpen(run)))
-        return { dismissed: true };
+        return { state: "dismissed" };
     await escape(); // one retry
-    return { dismissed: !(await sheetStillOpen(run)) };
+    return { state: (await sheetStillOpen(run)) ? "may-remain" : "dismissed" };
+}
+/**
+ * The dialog-class reachability GATE (SESSGATE, #480), run AFTER the reveal/
+ * activate preamble (which surfaces a window in a healthy session) and BEFORE any
+ * menu press. Three outcomes matched to the live session state:
+ *   - reachable                  → proceed;
+ *   - not reachable, "session"   → REFUSE (locked screen / full-screen Space —
+ *                                  the certain-failure case): block, zero mutation;
+ *   - not reachable, "window"    → RELOCATE: only Things' window is off the
+ *                                  current Space, so run the app-level close+reopen
+ *                                  that pulls it back, then RE-PROBE closed-loop.
+ *                                  Reachable now → proceed (disclosed); still not →
+ *                                  block with the Space remediation.
+ */
+async function ensureWindowReachable(run) {
+    const first = await probeSessionReachability(run, STEP_TIMEOUT_MS);
+    if (first.reachable)
+        return { ok: true, relocated: false };
+    if (first.scope === "session")
+        return { ok: false, verdict: first };
+    // scope "window": Things' window is on another Space (or absent) while the
+    // session is otherwise fine — try to bring it to the current Space, then re-probe.
+    await run({
+        primitive: "resolve",
+        label: "move the Things window to the current desktop",
+        script: axCloseReopenActivateScript(),
+    }, STEP_TIMEOUT_MS);
+    const second = await probeSessionReachability(run, STEP_TIMEOUT_MS);
+    if (second.reachable)
+        return { ok: true, relocated: true };
+    return { ok: false, verdict: second.reachable ? first : second };
+}
+/** The blocked ExecuteResult a dialog-class op returns when the session is unreachable. */
+function blockedReachability(verdict) {
+    return {
+        exitCode: 4,
+        stdout: "",
+        stderr: `${verdict.detail} ${verdict.remediation}`,
+        blocked: {
+            hazard: H_UI_SESSION_UNREACHABLE,
+            detail: verdict.detail,
+            remediation: verdict.remediation,
+        },
+    };
 }
 /**
  * resolve-frame: read the element's on-screen frame (top-left origin, points)
@@ -314,40 +469,78 @@ function clickPointCommand(x, y, label) {
     return { primitive: "click-point", label, lang: "javascript", script: jxaClickScript(x, y) };
 }
 /**
- * set-datetime: set the Repeat dialog's `AXDateTimeArea` (reminder time / "ends
- * on date" bound) via the ObjC AX bridge. Things' date/time control holds an
- * NSDate, and System Events cannot write it (`set value … to <date>` → -10000,
- * UIC6), so — like the mouse-synthesis primitive — this runs in JXA and calls
- * `AXUIElementSetAttributeValue(…, AXValue, <NSDate>)` directly. The control is
- * found by ROLE within Things' front dialog (there is exactly one during a
- * reminder/end-date step; the matrix never sets both at once), polled briefly
- * so it is caught right after the checkbox/pop-up that reveals it, and the
- * script THROWS when absent so the driver fails closed. `spec` is
- * `time:HH:mm` (keep the control's date, overwrite the time-of-day) or
- * `date:YYYY-MM-DD` (overwrite the date at midnight). One stable JXA shape.
+ * set-datetime: set ONE of the Repeat dialog's `AXDateTimeArea` controls via the
+ * ObjC AX bridge. Things' date/time controls hold an NSDate, and System Events
+ * cannot write them (`set value … to <date>` → -10000, UIC6), so — like the
+ * mouse-synthesis primitive — this runs in JXA and calls
+ * `AXUIElementSetAttributeValue(…, AXValue, <NSDate>)` directly.
+ *
+ * A fixed rule can expose up to THREE date areas at once — "Next:" (first
+ * occurrence), "Ends: on date", and the reminder time (ANCH2 census). Targeting
+ * "the first AXDateTimeArea by role" is therefore AMBIGUOUS — that ambiguity
+ * collapsed the series when `--ends-on` added a second area (oddities §8v, now
+ * retracted) and made the reminder look undrivable (UIC6-g, now retracted). This
+ * driver selects DETERMINISTICALLY by `target` (ANCH2, docs/lab/anch2-next-field.md):
+ *   - `reminder` — the only area carrying a time-of-day (the date pickers sit at
+ *     midnight); falls back to the bottom-most area if none carry a time.
+ *   - `next` — the TOP (smallest-y) midnight date picker.
+ *   - `ends` — the BOTTOM (largest-y) midnight date picker (present only once
+ *     "Ends: on date" is selected).
+ * The areas are polled briefly (revealed a beat after the checkbox/pop-up), and
+ * the script THROWS a NAMED, structured error when the addressed control is
+ * absent — reporting which target was sought and the FULL date-area inventory of
+ * the current dialog state (count + per-area y / time-of-day) — so a dialog shape
+ * that does not present the target (e.g. the deadline-mode variant, YANCH1 #493)
+ * fails closed with an actionable message, never an uncaught `-[__NSArray0
+ * objectAtIndex:]` (-2700) from indexing an empty collection. It then READS THE
+ * CONTROL BACK after the write and throws if the committed value differs from the
+ * request: a control that silently rejects the write (the macOS error beep the
+ * user hears) must fail the step loudly, never leave a garbled/default value to be
+ * verified as ok (YANCH1; UIC6-g refuse-rather-than-commit precedent). `spec` is
+ * `time:HH:mm` (keep the date, set the time-of-day) or `date:YYYY-MM-DD` (set the
+ * calendar date at midnight). One stable JXA shape.
  */
-export function axSetDateTimeScript(spec) {
+export function axSetDateTimeScript(spec, target) {
     return `ObjC.import('Foundation'); ObjC.import('AppKit'); ObjC.import('ApplicationServices');
 function attr(el,name){ var out=Ref(); if($.AXUIElementCopyAttributeValue(el,$(name),out)!==0) return null; return ObjC.castRefToObject(out[0]); }
 function rolestr(el){ var v=attr(el,'AXRole'); return v? v.js : ''; }
 function kids(el){ var c=attr(el,'AXChildren'); if(!c) return []; var a=[]; for(var i=0;i<c.count;i++) a.push(c.objectAtIndex(i)); return a; }
-function find(el,role,depth){ if(depth<0) return null; if(rolestr(el)===role) return el; var ks=kids(el); for(var i=0;i<ks.length;i++){ var r=find(ks[i],role,depth-1); if(r) return r;} return null; }
+function collect(el,role,depth,out){ if(depth<0) return; if(rolestr(el)===role) out.push(el); var ks=kids(el); for(var i=0;i<ks.length;i++) collect(ks[i],role,depth-1,out); }
+function posY(el){ var p=attr(el,'AXPosition'); if(!p) return 0; var d=ObjC.castRefToObject($.CFCopyDescription(p)).js; var m=String(d).match(/y:([-0-9.]+)/); return m? +m[1] : 0; }
+function timeOfDay(el){ var v=attr(el,'AXValue'); if(!v) return -1; var cal=$.NSCalendar.currentCalendar; return cal.componentFromDate($.NSCalendarUnitHour,v)*60 + cal.componentFromDate($.NSCalendarUnitMinute,v); }
+function pick(areas,target){
+  if(areas.length===0) return null;
+  var sorted=areas.slice().sort(function(a,b){ return posY(a)-posY(b); });
+  if(target==='reminder'){
+    var timed=sorted.filter(function(a){ return timeOfDay(a)>0; });
+    return timed.length? timed[timed.length-1] : sorted[sorted.length-1];
+  }
+  var midnight=sorted.filter(function(a){ return timeOfDay(a)===0; });
+  if(midnight.length===0) midnight=sorted;
+  return target==='ends' ? midnight[midnight.length-1] : midnight[0];
+}
+function inv(areas){ var s=[]; for(var i=0;i<areas.length;i++){ s.push('#'+i+'(y='+Math.round(posY(areas[i]))+',tod='+timeOfDay(areas[i])+')'); } return areas.length? s.join(' ') : '(none)'; }
+function ymdStr(el,cal){ var v=attr(el,'AXValue'); if(!v) return null; var y=cal.componentFromDate($.NSCalendarUnitYear,v), m=cal.componentFromDate($.NSCalendarUnitMonth,v), dd=cal.componentFromDate($.NSCalendarUnitDay,v); return y+'-'+('0'+m).slice(-2)+'-'+('0'+dd).slice(-2); }
+function hmStr(el,cal){ var v=attr(el,'AXValue'); if(!v) return null; var h=cal.componentFromDate($.NSCalendarUnitHour,v), mi=cal.componentFromDate($.NSCalendarUnitMinute,v); return h+':'+('0'+mi).slice(-2); }
 function run(){
   var apps=$.NSRunningApplication.runningApplicationsWithBundleIdentifier('com.culturedcode.ThingsMac');
   if(!apps || apps.count===0) throw new Error('Things not running');
-  var pid=apps.objectAtIndex(0).processIdentifier;
-  var app=$.AXUIElementCreateApplication(pid);
-  var dt=null;
-  for(var t=0;t<20 && !dt;t++){ dt=find(app,'AXDateTimeArea',16); if(!dt) $.NSThread.sleepForTimeInterval(0.1); }
-  if(!dt) throw new Error('no AXDateTimeArea in the Repeat dialog');
+  var app=$.AXUIElementCreateApplication(apps.objectAtIndex(0).processIdentifier);
+  var target=${JSON.stringify(target)};
   var spec=${JSON.stringify(spec)};
+  // Poll for the addressed area. 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.
+  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); }
+  if(!dt) throw new Error('set-datetime '+target+': this Repeat-dialog state presents '+areas.length+' date area(s) ['+inv(areas)+'] but none is the '+target+' control — the requested first occurrence / bound cannot be set in this dialog shape');
   var cal=$.NSCalendar.currentCalendar;
   var d;
   if(spec.indexOf('time:')===0){
-    // Set the time-of-day on the control's own (today's) date via the purpose-
-    // built calendar API — component-bag mutation via JXA silently drops the
-    // hour, leaking the current wall-clock hour into the reminder (UIC6).
-    var cur=attr(dt,'AXValue'); if(!cur) throw new Error('date/time control has no value');
+    // Set the time-of-day on the control's own date via the purpose-built
+    // calendar API — component-bag mutation via JXA silently drops the hour,
+    // leaking the current wall-clock hour into the reminder (UIC6).
+    var cur=attr(dt,'AXValue'); if(!cur) throw new Error('set-datetime '+target+': the date/time control has no value to anchor the time on');
     var hm=spec.slice(5).split(':');
     d=cal.dateBySettingHourMinuteSecondOfDateOptions(+hm[0], +hm[1], 0, cur, 0);
   } else if(spec.indexOf('date:')===0){
@@ -358,8 +551,18 @@ function run(){
   } else { throw new Error('bad datetime spec: '+spec); }
   if(!d) throw new Error('could not build date from '+spec);
   var err=$.AXUIElementSetAttributeValue(dt,$('AXValue'),d);
-  if(err!==0) throw new Error('AXValue set failed err='+err);
+  if(err!==0) throw new Error('set-datetime '+target+': the control refused the write (AX err='+err+')');
   $.NSThread.sleepForTimeInterval(0.2);
+  // READ-BACK: a control can accept the AX write (err 0) yet reject the value —
+  // the macOS error beep — leaving its prior/default value. Fail the step loudly
+  // rather than let a garbled commit verify as ok (YANCH1 #493).
+  if(spec.indexOf('date:')===0){
+    var got=ymdStr(dt,cal); var want=spec.slice(5);
+    if(got!==want) throw new Error('set-datetime '+target+' rejected: the control committed '+(got||'(no value)')+', not the requested '+want+' — the write did not take');
+  } else {
+    var gott=hmStr(dt,cal); var wanth=spec.slice(5).split(':'); var wantt=(+wanth[0])+':'+('0'+(+wanth[1])).slice(-2);
+    if(gott!==wantt) throw new Error('set-datetime '+target+' rejected: the control committed '+(gott||'(no value)')+', not the requested '+wantt+' — the write did not take');
+  }
   return 'OK';
 }`;
 }
@@ -399,6 +602,40 @@ function defaultRun(command, timeoutMs) {
         });
     });
 }
+/**
+ * Wrap the dispatch seam so every osascript hop is recorded. The last-dispatched
+ * step is noted on the in-flight-write marker (so a SIGTERM/SIGINT can name it,
+ * even with tracing off), and — when tracing is on — a `ui-dispatch` start/end
+ * pair lands in the trace carrying the hop's duration and outcome. This
+ * per-osascript granularity is exactly what reconstructs a hang: the timeline
+ * shows which step's osascript was in flight, and for how long, when it stopped
+ * (TRACE1 #487). Overhead when tracing is off is one boolean check + a field write.
+ */
+function tracingRun(inner) {
+    return async (command, timeoutMs) => {
+        noteInflightStep(command.label);
+        if (!traceActive())
+            return inner(command, timeoutMs);
+        const started = Date.now();
+        trace(() => ({
+            phase: "ui-dispatch",
+            event: "start",
+            primitive: command.primitive,
+            label: command.label,
+        }));
+        const res = await inner(command, timeoutMs);
+        trace(() => ({
+            phase: "ui-dispatch",
+            event: "end",
+            primitive: command.primitive,
+            label: command.label,
+            durationMs: Date.now() - started,
+            ok: res.ok,
+            timedOut: res.timedOut === true,
+        }));
+        return res;
+    };
+}
 /** The element paths the preflight canary resolves (static steps only). */
 function canaryPaths(recipe) {
     const out = [];
@@ -485,7 +722,13 @@ export function commandForStep(step, targetUuid) {
                 primitive: "set-datetime",
                 label: step.label,
                 lang: "javascript",
-                script: axSetDateTimeScript(step.value ?? ""),
+                script: axSetDateTimeScript(step.value ?? "", step.dtTarget ?? "next"),
+            };
+        case "ensure-checkbox":
+            return {
+                primitive: "ensure-checkbox",
+                label: step.label,
+                script: axEnsureCheckboxScript(step.path ?? "", step.checkboxTarget === true),
             };
         case "wait":
             return { primitive: "wait", label: step.label, script: axResolveScript(step.path ?? "") };
@@ -501,6 +744,12 @@ export function commandForStep(step, targetUuid) {
                 label: step.label,
                 script: axSelectHeadingRowScript(step.path ?? "", Number(step.value ?? "0")),
             };
+        case "assert-eligible":
+            return {
+                primitive: "assert-eligible",
+                label: step.label,
+                script: axAssertEligibleScript(step.value ?? targetUuid, step.path ?? ""),
+            };
         case "key":
             return { primitive: "key", label: step.label, script: axKeyScript(step.keys ?? "") };
         case "click-element":
@@ -567,20 +816,69 @@ async function driveClickElement(step, run) {
     }
     return { ok: true };
 }
-async function drive(recipe, run, aux) {
+async function drive(recipe, run, aux, budgetMs = DEFAULT_UI_DRIVE_BUDGET_MS) {
     const done = [];
-    // `dismissed`: true = abort verified the sheet gone; false = abort could NOT
-    // confirm dismissal (warn it may remain open — 0½ defect (d): never claim a
-    // dismissal we did not see); undefined = no sheet was opened / no abort ran.
-    const partial = (failed, why, dismissed) => {
+    // The overall-drive WATCHDOG (TRACE1 #487). A drive can outlast the caller's
+    // own timeout on a slow production database (large + Things-Cloud syncing
+    // commits the Repeat dialog several times slower than the lab golden), which
+    // is how #487 fired: the caller's 30s kill left empty stdout and no retained
+    // exit code. This budget lets the CLI give up FIRST — clearing any open dialog
+    // and returning an honest, uncertain-outcome timeout — so the caller always
+    // receives structured output. Checked between steps (per-step execFile
+    // timeouts bound each osascript, so a step boundary is never far off).
+    const driveStart = Date.now();
+    const driveDeadline = driveStart + budgetMs;
+    const overBudget = () => Date.now() >= driveDeadline;
+    const watchdogResult = async (lastStep) => {
+        // Attempt the SESSGATE dialog clearance so the watchdog never leaves a stuck
+        // modal behind (#485), then report honestly. The outcome is UNCERTAIN: a rule
+        // whose OK press was mid-commit could still land — the pipeline re-verifies
+        // and shapes the final result accordingly.
+        const clear = await clearDialog(run);
+        trace(() => ({
+            phase: "watchdog",
+            budgetMs,
+            elapsedMs: Date.now() - driveStart,
+            lastStep,
+            clear: clear.state,
+            completed: done,
+        }));
+        return {
+            exitCode: 1,
+            stdout: `ui drive watchdog stopped after ${done.length} step(s): ${done.join(" → ") || "nothing"}`,
+            stderr: `ui drive exceeded its ${Math.round(budgetMs / 1000)}s budget at "${lastStep}"`,
+            timedOut: true,
+            watchdog: {
+                budgetMs,
+                elapsedMs: Date.now() - driveStart,
+                lastStep,
+                clear: clear.state,
+                tracePath: tracePath(),
+            },
+        };
+    };
+    // A note prepended to the success summary when the drive had to RELOCATE the
+    // Things window to the current Space to open its dialog (SESSGATE wrong-Space
+    // recovery) — surfaced to the caller as a disclosure warning.
+    let relocationNote = "";
+    // `clear`: how a half-open sheet was cleaned up after a failure (honest — never
+    // claim a dismissal we could not see, SESSGATE #480); undefined = no sheet was
+    // opened / no cleanup ran (a benign preamble/canary failure).
+    const partial = (failed, why, clear) => {
         const base = `ui drive stopped at "${failed}" (${why}). Completed: ${done.join(" → ") || "nothing"}.`;
-        const cleanup = dismissed === true
-            ? " The open sheet/popover was dismissed (Escape, confirmed gone)."
-            : dismissed === false
-                ? " WARNING: a sheet or popover may still be open in Things — Escape did not dismiss it." +
-                    " Dismiss it manually before retrying (a leftover sheet disables the menu bar and will" +
-                    " make the next drive's preflight fail)."
-                : "";
+        const cleanup = clear === undefined
+            ? ""
+            : clear.state === "dismissed"
+                ? " The open sheet/popover was dismissed (Escape, confirmed gone)."
+                : clear.state === "cleared-blind"
+                    ? " Things had no window reachable on the current screen (the Mac may be locked, or a" +
+                        " full-screen app is covering the desktop), so the open dialog could not be confirmed" +
+                        " through the on-screen layer — the Things window was closed and reopened to clear it," +
+                        " discarding any partially-entered rule. Unlock the Mac or leave the full-screen app" +
+                        " before retrying."
+                    : " WARNING: a sheet or popover may still be open in Things — Escape did not dismiss it." +
+                        " Dismiss it manually before retrying (a leftover sheet disables the menu bar and will" +
+                        " make the next drive's preflight fail).";
         return refusal(base + cleanup);
     };
     // 0. Run the leading reveal/activate preamble BEFORE the canary. The Items
@@ -603,6 +901,22 @@ async function drive(recipe, run, aux) {
     // Let the selection settle so the menu bar repopulates before the canary reads it.
     if (idx > 0)
         await new Promise((r) => setTimeout(r, SETTLE_AFTER_REVEAL_MS));
+    // 0½. Session-reachability GATE for dialog-class ops (SESSGATE, #480). A recipe
+    //     that opens a sheet on the main window needs that window AX-reachable on
+    //     the current Space. Probed AFTER the preamble (which surfaces a window in a
+    //     healthy session) and BEFORE the canary/press (no mutation yet): a locked /
+    //     full-screen session REFUSES (blocked, zero mutation); a window merely on
+    //     another Space is RELOCATED back and disclosed. Menu-only recipes skip this.
+    if (recipe.needsWindowReachability === true) {
+        const reach = await ensureWindowReachable(run);
+        if (!reach.ok)
+            return blockedReachability(reach.verdict);
+        if (reach.relocated) {
+            relocationNote =
+                "the Things window was on another desktop, so it was moved to the desktop you're viewing " +
+                    "to open the dialog. ";
+        }
+    }
     // 1. Recipe canary: resolve every statically-reachable element (now that the
     //    target is selected). A miss refuses the whole drive before anything is
     //    pressed. (This is also the localization check: English titles must resolve.)
@@ -631,6 +945,11 @@ async function drive(recipe, run, aux) {
     // 2. Execute the remaining steps in order; a dynamic element is waited-for.
     for (let i = idx; i < recipe.steps.length; i += 1) {
         let step = recipe.steps[i];
+        // Overall-drive watchdog: if the budget is spent, stop at THIS step boundary
+        // (the per-step execFile timeouts keep the boundary close), clear any open
+        // dialog, and return the honest uncertain-outcome timeout (TRACE1 #487).
+        if (overBudget())
+            return watchdogResult(step.label);
         if (step.primitive === "wait") {
             // A candidate-addressed wait polls for ANY of its shapes to appear (the
             // dialog opening as an attached sheet OR a detached AXUnknown window).
@@ -638,8 +957,8 @@ async function drive(recipe, run, aux) {
             const ok = await waitForAnyElement(step.pathCandidates ?? [step.path ?? ""], step.label, step.timeoutMs ?? STEP_TIMEOUT_MS, run);
             if (!ok) {
                 // the abort keystroke must land (and be verified) before returning the partial-state report
-                const { dismissed } = await verifiedAbort(run);
-                return partial(step.label, "the expected element never appeared within the timeout", dismissed);
+                const clear = await clearDialog(run);
+                return partial(step.label, "the expected element never appeared within the timeout", clear);
             }
             done.push(step.label);
             continue;
@@ -665,9 +984,9 @@ async function drive(recipe, run, aux) {
             const effective = await resolveStepPath(step, run);
             if (effective === null) {
                 // dismiss whatever opened (and verify) before reporting
-                const { dismissed } = await verifiedAbort(run);
+                const clear = await clearDialog(run);
                 return partial(step.label, "none of its expected element shapes resolved (neither the attached sheet nor the " +
-                    "detached repeat editor window)", dismissed);
+                    "detached repeat editor window)", clear);
             }
             step = { ...step, path: effective };
         }
@@ -680,7 +999,7 @@ async function drive(recipe, run, aux) {
             const res = await run(command, STEP_TIMEOUT_MS);
             if (!res.ok || res.stdout.trim() !== "OK") {
                 // clear any transient state (and verify) before reporting
-                const { dismissed } = await verifiedAbort(run);
+                const clear = await clearDialog(run);
                 const noMatch = step.primitive === "select-heading-row"
                     ? "the project view exposed no selectable heading row at the target position — the " +
                         "heading may have been converted/deleted already, or the project's headings changed"
@@ -690,7 +1009,29 @@ async function drive(recipe, run, aux) {
                     ? noMatch
                     : res.timedOut === true
                         ? "the row-selection step timed out"
-                        : res.stderr.trim() || "the row-selection step failed", dismissed);
+                        : res.stderr.trim() || "the row-selection step failed", clear);
+            }
+            done.push(step.label);
+            continue;
+        }
+        if (step.primitive === "assert-eligible") {
+            // ADR1 (#480): fail EARLY + NAMED when the reveal did not land an eligible
+            // selection, rather than letting a disabled-menu no-op surface downstream
+            // as an opaque dialog-wait timeout. The script returns "OK" or a diagnostic
+            // (NOTSEL…/WRONGSEL…/DISABLED…) that IS the human-readable failure reason.
+            // the selection/enabled state must be confirmed before the menu is pressed
+            const res = await run(command, STEP_TIMEOUT_MS);
+            const verdict = res.stdout.trim();
+            if (!res.ok || verdict !== "OK") {
+                // clear any transient state (and verify) before reporting
+                const clear = await clearDialog(run);
+                return partial(step.label, res.ok
+                    ? verdict !== ""
+                        ? verdict
+                        : "the target to-do was not confirmed selected/eligible after the reveal"
+                    : res.timedOut === true
+                        ? "the eligibility check timed out"
+                        : res.stderr.trim() || "the eligibility check failed", clear);
             }
             done.push(step.label);
             continue;
@@ -701,9 +1042,9 @@ async function drive(recipe, run, aux) {
             // the click depends on the UI state the previous step produced
             const outcome = await driveClickElement(step, run);
             if (!outcome.ok) {
-                // dismiss whatever the click opened (and verify) before reporting
-                const dismissed = outcome.needsAbort === true ? (await verifiedAbort(run)).dismissed : undefined;
-                return partial(step.label, outcome.why ?? "the click failed", dismissed);
+                // clear whatever the click opened (honest cleanup) before reporting
+                const clear = outcome.needsAbort === true ? await clearDialog(run) : undefined;
+                return partial(step.label, outcome.why ?? "the click failed", clear);
             }
             done.push(step.label);
             continue;
@@ -711,15 +1052,20 @@ async function drive(recipe, run, aux) {
         // each recipe step depends on the UI state the previous step produced; they cannot be parallelized
         const res = await run(command, STEP_TIMEOUT_MS);
         if (!res.ok) {
-            // dismiss the half-open sheet/popover (and verify) before reporting partial state
-            const dismissed = step.primitive !== "reveal" && step.primitive !== "activate"
-                ? (await verifiedAbort(run)).dismissed
+            // clear the half-open sheet/popover (honest — never claim an unconfirmed
+            // dismissal) before reporting partial state
+            const clear = step.primitive !== "reveal" && step.primitive !== "activate"
+                ? await clearDialog(run)
                 : undefined;
-            return partial(step.label, res.timedOut === true ? "the step timed out" : res.stderr.trim() || "the step failed", dismissed);
+            return partial(step.label, res.timedOut === true ? "the step timed out" : res.stderr.trim() || "the step failed", clear);
         }
         done.push(step.label);
     }
-    return { exitCode: 0, stdout: `drove ${done.length} step(s): ${done.join(" → ")}`, stderr: "" };
+    return {
+        exitCode: 0,
+        stdout: `${relocationNote}drove ${done.length} step(s): ${done.join(" → ")}`,
+        stderr: "",
+    };
 }
 async function waitForElement(command, timeoutMs, run) {
     const deadline = Date.now() + timeoutMs;
@@ -796,6 +1142,11 @@ function disabledMatrix() {
  */
 export function createUiVector(config, run = defaultRun, aux = {}) {
     const enabled = config.ui.enabled;
+    const budgetMs = config.ui.driveBudgetMs ?? DEFAULT_UI_DRIVE_BUDGET_MS;
+    // Every osascript hop runs through the tracing seam: it notes the step on the
+    // in-flight marker (for the signal handler) and, when tracing is on, records a
+    // start/end pair with timing/outcome (TRACE1 #487).
+    const tracedRun = tracingRun(run);
     return {
         id: "ui",
         matrix: enabled ? enabledMatrix() : disabledMatrix(),
@@ -806,8 +1157,13 @@ export function createUiVector(config, run = defaultRun, aux = {}) {
             if (invocation.recipe === undefined) {
                 return refusal("ui invocation carried no recipe (compile bug).");
             }
-            return drive(invocation.recipe, run, aux);
+            return drive(invocation.recipe, tracedRun, aux, budgetMs);
         },
+        // 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),
     };
 }
 //# sourceMappingURL=ui.js.map