things-api 0.19.1 → 0.19.3

package/dist/write/vectors/ui-state.js

@@ -0,0 +1,452 @@
+/** How deep a stack of dialogs the walk will follow before giving up. */
+const MAX_SHEET_DEPTH = 6;
+/**
+ * Resolve the dialog IN FRONT — the innermost of a stack — and record how deep
+ * the stack goes. Written as a snippet because the census and the dismissal must
+ * agree on which dialog they mean, to the element.
+ *
+ * Sheets STACK (MODALX1 §6, golden-v4 / 3.23): a dialog raised while another is
+ * standing becomes an `AXSheet` CHILD of the one below it, not a sibling on the
+ * window — measured with two `things:///add` URL-consent alerts nesting inside a
+ * Repeat sheet — and dismissal is strictly LIFO. So a census that reads only the
+ * window's own `sheet 1` sees the bottom of the stack and misidentifies what
+ * actually owns the screen, and a dismissal aimed there presses a button behind
+ * a modal. Both walk to the top instead.
+ *
+ * Runs inside a `tell process "Things3"` block; leaves `shellRef` (or
+ * `missing value`), `sheetForm` and `sheetDepth` bound.
+ */
+export const AX_DIALOG_SHELL_SNIPPET = `		set shellRef to missing value
+		set sheetForm to "none"
+		set sheetDepth to 0
+		try
+			-- positional-ok: the one attached sheet a window can present, which is
+			-- the BOTTOM of any stack; the walk below climbs to the top.
+			set shellRef to sheet 1 of (first window whose subrole is "AXStandardWindow")
+			set sheetForm to "attached"
+			set sheetDepth to 1
+		end try
+		if shellRef is missing value then
+			try
+				set dws to (windows whose subrole is "AXUnknown" and size is not {40, 40})
+				if (count of dws) > 0 then
+					set shellRef to item 1 of dws
+					set sheetForm to "detached"
+					set sheetDepth to 1
+				end if
+			end try
+		end if
+		if shellRef is not missing value then
+			repeat ${MAX_SHEET_DEPTH} times
+				set nested to missing value
+				try
+					if (exists sheet 1 of shellRef) then set nested to sheet 1 of shellRef
+				end try
+				if nested is missing value then exit repeat
+				set shellRef to nested
+				set sheetDepth to sheetDepth + 1
+			end repeat
+		end if`;
+/** Probes whose absence makes the census unusable for a keystroke decision. */
+const CRITICAL_PROBES = ["running", "frontmost", "dialog"];
+/** Every probe name the census can report, for parsing its record back. */
+const KNOWN_PROBES = new Set([
+    "running",
+    "frontmost",
+    "dialog",
+    "frontapp",
+    "focus",
+]);
+/**
+ * Per-APPLE-EVENT budget for every read in the census (`with timeout of N
+ * seconds`). Without one, osascript's default is two MINUTES: a System Events
+ * call that does not come back is then bounded only by the caller's own process
+ * deadline, which is how issue #629's field incident spent ~15s per inspection
+ * and ~56s per drive discovering nothing. With one, a read that will not answer
+ * raises AppleScript error -1712 and the census carries on to the next probe —
+ * or stops, if the probe was one the caller decides on.
+ */
+const PROBE_TIMEOUT_S = 2;
+/**
+ * Wall-clock budget for the WHOLE census, checked between probes. `with
+ * timeout` bounds one Apple event, not a run of them, so a surface that is
+ * merely slow (rather than wedged) could still add up. Past this, the remaining
+ * probes are skipped and reported as stalled rather than waited on.
+ */
+const CENSUS_BUDGET_S = 8;
+/**
+ * The transport deadline for one census hop — the backstop under the in-script
+ * budgets, not the mechanism. Deliberately far below the 15s step timeout that
+ * bounded the old single-shot script: nothing here may take this long, and if
+ * it does the caller must hear about it while the drive can still be aborted
+ * cleanly rather than after four of them have gone by.
+ */
+export const CENSUS_TIMEOUT_MS = 12_000;
+/** Did a probe the caller has to DECIDE on fail to answer? */
+export function censusUnverifiable(state) {
+    if (state === null)
+        return true;
+    return CRITICAL_PROBES.some((p) => state.stalledProbes.includes(p) || state.failedProbes.includes(p));
+}
+/** Name the probes that did not answer, for a diagnostic someone has to act on. */
+export function describeUnprovenProbes(state) {
+    const label = {
+        running: "whether Things is running",
+        frontmost: "whether Things owns the screen",
+        dialog: "which dialog is open",
+        frontapp: "which application owns the screen",
+        focus: "which element has keyboard focus",
+    };
+    const parts = [];
+    if (state.stalledProbes.length > 0) {
+        parts.push(`did not answer in time: ${state.stalledProbes.map((p) => label[p]).join(", ")}`);
+    }
+    if (state.failedProbes.length > 0) {
+        parts.push(`could not be read: ${state.failedProbes.map((p) => label[p]).join(", ")}`);
+    }
+    return parts.join("; ");
+}
+/** A recognizable token in the script so a test runner can key off the ui-state command. */
+export const UI_STATE_MARKER = "-- ui-state census (read-only)";
+/** The label every ui-state dispatch carries (one stable command shape). */
+export const UI_STATE_LABEL = "read the window and focus state";
+/** The Things application's process name — the frontmost value that means "us". */
+export const THINGS_PROCESS = "Things3";
+/**
+ * The census script — ADDRESSED probes, each on its own Apple-event budget
+ * (issue #629).
+ *
+ * WHAT CHANGED, AND WHY IT HAD TO. The 0.19.2 census was one unbounded script
+ * that opened with two UNADDRESSED queries: `first application process whose
+ * frontmost is true` (the entire process table enumerated) and `value of
+ * attribute "AXFocusedUIElement"` on whatever that returned (a system-wide
+ * focused-element resolution). Everything else the ui vector runs — every step
+ * the field incident's log shows succeeding, inside the very sheet the census
+ * could not describe — is addressed: `tell process "Things3" to …`. So the one
+ * script that stalled was the one script that left the addressed style, and it
+ * stalled on the critical path of BOTH the per-step guard and the cleanup that
+ * was supposed to recover from it. Rebuilt here so that:
+ *
+ *   - the decision-critical facts are ADDRESSED and are proven FIRST;
+ *   - every read carries `with timeout of ${PROBE_TIMEOUT_S} seconds`, so a
+ *     surface that will not answer costs seconds, not the caller's whole
+ *     deadline;
+ *   - a critical probe that does not answer STOPS the census then and there —
+ *     the remaining probes cannot change what the caller must now do (abort and
+ *     clean up), so waiting for them is pure latency;
+ *   - the two unaddressed queries survive only as DECORATION, last, skipped
+ *     entirely when the addressed probes already answered the question they
+ *     were there to answer.
+ *
+ * Every probe still degrades one field rather than failing the census, and what
+ * could not be proven is NAMED (`stalled=` / `failed=`) instead of silently
+ * reading as a clean "nothing is open".
+ */
+export function axUiStateScript() {
+    return `${UI_STATE_MARKER}
+set frontName to ""
+set frontIsThings to false
+set focusRole to ""
+set focusSub to ""
+set canInspect to true
+set thingsRunning to false
+set sheetForm to "none"
+set sheetKind to "none"
+set sheetDepth to 0
+set census to ""
+set stalled to ""
+set failed to ""
+set halted to false
+set t0 to (current date)
+
+-- P1 running: a name-keyed lookup, no Accessibility round-trip.
+try
+	with timeout of ${PROBE_TIMEOUT_S} seconds
+		tell application "System Events" to set thingsRunning to (exists application process "${THINGS_PROCESS}")
+	end timeout
+on error errMsg number errNum
+	if errNum is -1712 then
+		set stalled to stalled & "running "
+	else
+		set failed to failed & "running "
+	end if
+	set halted to true
+end try
+
+-- P2 frontmost, ADDRESSED: the single fact the per-step input guard decides on.
+if (not halted) and thingsRunning then
+	try
+		with timeout of ${PROBE_TIMEOUT_S} seconds
+			tell application "System Events" to tell process "${THINGS_PROCESS}" to set frontIsThings to (frontmost as boolean)
+		end timeout
+		if frontIsThings then set frontName to "${THINGS_PROCESS}"
+	on error errMsg number errNum
+		if errNum is -1712 then
+			set stalled to stalled & "frontmost "
+		else
+			set failed to failed & "frontmost "
+		end if
+		set halted to true
+	end try
+end if
+
+-- P3 dialog: shell, form, stack depth and control census — all addressed
+-- inside the Things process, which is the shape every working drive step uses.
+if (not halted) and thingsRunning then
+	try
+		with timeout of ${PROBE_TIMEOUT_S} seconds
+			tell application "System Events" to tell process "${THINGS_PROCESS}"
+${AX_DIALOG_SHELL_SNIPPET}
+				if shellRef is not missing value then
+					set nCb to -1
+					set nPu to -1
+					set nBt to -1
+					set nGp to -1
+					set nTf to -1
+					try
+						set nCb to (count of checkboxes of shellRef)
+					end try
+					try
+						set nPu to (count of pop up buttons of shellRef)
+					end try
+					try
+						set nBt to (count of buttons of shellRef)
+					end try
+					try
+						set nGp to (count of groups of shellRef)
+					end try
+					try
+						set nTf to (count of text fields of shellRef)
+					end try
+					set census to "cb:" & nCb & " pu:" & nPu & " bt:" & nBt & " gp:" & nGp & " tf:" & nTf
+					set winId to ""
+					try
+						set winId to (value of attribute "AXIdentifier" of shellRef) as text
+					end try
+					if winId starts with "MovePopUpDialog-" then
+						set sheetKind to "move-picker"
+					else if nCb is 2 and nPu is 1 and nBt is 2 and nGp is 1 and nTf is 0 then
+						set groupOk to false
+						try
+							set g to group 1 of shellRef
+							if ((count of text fields of g) + (count of pop up buttons of g)) > 0 then set groupOk to true
+						end try
+						if groupOk then set sheetKind to "repeat"
+					end if
+					if sheetKind is "none" then set sheetKind to "other"
+				end if
+			end tell
+		end timeout
+	on error errMsg number errNum
+		if errNum is -1712 then
+			set stalled to stalled & "dialog "
+		else
+			set failed to failed & "dialog "
+		end if
+		set halted to true
+	end try
+end if
+
+-- P4 frontapp: the ONLY enumeration left, and it runs only when the addressed
+-- probe has already said the screen is not ours — its whole job is naming the
+-- application in the refusal sentence.
+if (not halted) and (not frontIsThings) then
+	if ((current date) - t0) > ${CENSUS_BUDGET_S} then
+		set stalled to stalled & "frontapp "
+	else
+		try
+			with timeout of ${PROBE_TIMEOUT_S} seconds
+				tell application "System Events" to set frontName to (name of first application process whose frontmost is true) as text
+			end timeout
+		on error errMsg number errNum
+			if errNum is -1712 then
+				set stalled to stalled & "frontapp "
+			else
+				set failed to failed & "frontapp "
+			end if
+		end try
+	end if
+end if
+
+-- P5 focus: decoration, and the most expensive read in the census. Addressed at
+-- the process that owns the screen rather than resolved system-wide, run last,
+-- and skipped outright once the budget is spent. An ERROR here (as opposed to a
+-- timeout) is the secure-system-modal signature: macOS exposes no tree for one.
+if not halted then
+	if ((current date) - t0) > ${CENSUS_BUDGET_S} then
+		set stalled to stalled & "focus "
+	else
+		set focusTarget to frontName
+		if focusTarget is "" then
+			set stalled to stalled & "focus "
+		else
+			try
+				with timeout of ${PROBE_TIMEOUT_S} seconds
+					tell application "System Events" to tell process focusTarget
+						set fe to value of attribute "AXFocusedUIElement"
+						-- No focused element is a perfectly ordinary state (an app
+						-- with no key window); it is not an unreadable screen.
+						if fe is not missing value then
+							set focusRole to (role of fe) as text
+							try
+								set focusSub to (subrole of fe) as text
+							end try
+						end if
+					end tell
+				end timeout
+			on error errMsg number errNum
+				if errNum is -1712 then
+					set stalled to stalled & "focus "
+				else
+					set canInspect to false
+					set failed to failed & "focus "
+				end if
+			end try
+		end if
+	end if
+end if
+
+return "front=" & frontName & linefeed & "isfront=" & frontIsThings & linefeed & "running=" & thingsRunning & linefeed & "form=" & sheetForm & linefeed & "depth=" & sheetDepth & linefeed & "kind=" & sheetKind & linefeed & "census=" & census & linefeed & "role=" & focusRole & linefeed & "subrole=" & focusSub & linefeed & "inspectable=" & canInspect & linefeed & "stalled=" & stalled & linefeed & "failed=" & failed`;
+}
+/**
+ * Parse the census record into a {@link UiState}. Returns null when the output
+ * carries none of the expected keys (a transport error, or a script that never
+ * ran) — every caller treats that as UNKNOWN, never as "all clear".
+ */
+export function parseUiState(stdout) {
+    const fields = new Map();
+    for (const line of stdout.split(/\r?\n/)) {
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        fields.set(line.slice(0, eq).trim(), line.slice(eq + 1).trim());
+    }
+    if (!fields.has("kind") || !fields.has("inspectable"))
+        return null;
+    const probes = (key) => (fields.get(key) ?? "").split(/\s+/).filter((p) => KNOWN_PROBES.has(p));
+    const kindRaw = fields.get("kind") ?? "none";
+    const sheetKind = kindRaw === "repeat" || kindRaw === "move-picker" || kindRaw === "other" ? kindRaw : "none";
+    const formRaw = fields.get("form") ?? "none";
+    const sheetForm = formRaw === "attached" || formRaw === "detached" ? formRaw : "none";
+    const frontRaw = fields.get("front") ?? "";
+    const frontmostApp = frontRaw === "" ? null : frontRaw;
+    const role = fields.get("role") ?? "";
+    // AppleScript coerces an absent attribute to the literal words "missing
+    // value"; that is "no subrole", not a subrole named that.
+    const subroleRaw = fields.get("subrole") ?? "";
+    const subrole = subroleRaw === "missing value" ? "" : subroleRaw;
+    const census = fields.get("census") ?? "";
+    const depth = Number(fields.get("depth") ?? "0");
+    return {
+        thingsRunning: fields.get("running") === "true",
+        // Decided by the ADDRESSED probe, not by comparing a name the enumeration
+        // may never have been asked for (issue #629).
+        thingsFrontmost: fields.get("isfront") === "true",
+        frontmostApp,
+        sheetOpen: sheetKind !== "none",
+        sheetKind,
+        sheetForm,
+        sheetDepth: Number.isFinite(depth) ? depth : 0,
+        sheetControls: census === "" ? null : census,
+        focusOwner: frontmostApp === null ? null : { app: frontmostApp, role, subrole: subrole || null },
+        inspectable: fields.get("inspectable") === "true",
+        stalledProbes: probes("stalled"),
+        failedProbes: probes("failed"),
+    };
+}
+/**
+ * Read the census through the injected runner. Returns null on a transport
+ * failure — an UNKNOWN state, which every caller treats fail-closed (the guard
+ * refuses; the cleanup path does not send a blind Escape).
+ *
+ * `timeoutMs` defaults to {@link CENSUS_TIMEOUT_MS}: a census is not a drive
+ * step and must not borrow a drive step's patience (issue #629).
+ */
+export async function readUiState(run, timeoutMs = CENSUS_TIMEOUT_MS) {
+    const res = await run({ primitive: "resolve", label: UI_STATE_LABEL, script: axUiStateScript() }, timeoutMs);
+    if (!res.ok)
+        return null;
+    return parseUiState(res.stdout);
+}
+/**
+ * How to name the surface that owns the screen, for a refusal someone has to
+ * act on. Names the APPLICATION and the focused element's ROLE — never its
+ * contents. An un-inspectable frontmost surface is named as what it is: a
+ * system dialog macOS does not expose, which is the one case where the person
+ * at the keyboard has to look at the screen themselves.
+ */
+export function describeFocusOwner(state) {
+    if (state === null)
+        return "the window state could not be read";
+    // #629: an inspection that did not come back says nothing about who owns the
+    // screen — and saying "an unidentified application is frontmost" would read
+    // as a measurement. Name the probe that stalled instead.
+    if (censusUnverifiable(state)) {
+        return `the window state inspection did not complete (${describeUnprovenProbes(state)})`;
+    }
+    if (!state.inspectable) {
+        return ("a system dialog owns the screen — macOS does not expose it to other apps, so it cannot be " +
+            `identified from here${state.frontmostApp === null ? "" : ` (frontmost application: ${state.frontmostApp})`}`);
+    }
+    const app = state.frontmostApp ?? "an unidentified application";
+    const role = state.focusOwner?.role ?? "";
+    return role === ""
+        ? `${app} is frontmost`
+        : `${app} is frontmost and keyboard focus is on a ${role}`;
+}
+/**
+ * A one-line human summary of the census, for a diagnostic line or a warning.
+ *
+ * Reports WHAT EACH PROBE PROVED. A stalled probe leaves its clause reading
+ * "could not be determined" and is named at the end — never omitted, and never
+ * rendered as its default (issue #629: a census that could not see the open
+ * Repeat sheet used to report a clean screen).
+ */
+export function describeUiState(state) {
+    const unproven = (p) => state.stalledProbes.includes(p) || state.failedProbes.includes(p);
+    const trailer = () => {
+        const unprovenText = describeUnprovenProbes(state);
+        return unprovenText === "" ? "" : ` — ${unprovenText}`;
+    };
+    if (unproven("running")) {
+        return `nothing about the screen could be established${trailer()}`;
+    }
+    if (!state.thingsRunning && !unproven("frontmost")) {
+        return `Things is not running${trailer()}`;
+    }
+    const front = unproven("frontmost")
+        ? "whether Things owns the screen could not be determined"
+        : state.thingsFrontmost
+            ? "Things is frontmost"
+            : unproven("frontapp")
+                ? "another application is frontmost (it could not be named)"
+                : `${state.frontmostApp ?? "an unidentified application"} is frontmost`;
+    if (unproven("dialog")) {
+        return `${front}; whether a dialog is open in Things could not be determined${trailer()}`;
+    }
+    const sheet = state.sheetKind === "none"
+        ? "no dialog is open in Things"
+        : state.sheetKind === "repeat"
+            ? `the Repeat dialog is open (${state.sheetForm})`
+            : state.sheetKind === "move-picker"
+                ? `the Move… picker is open (${state.sheetForm})`
+                : `an unrecognized dialog is open in Things (${state.sheetForm})`;
+    // A stack means the thing in front is sitting ON another dialog, and each one
+    // has to be dismissed in turn (MODALX1 §6).
+    const stacked = state.sheetDepth > 1 ? `, on top of ${state.sheetDepth - 1} more` : "";
+    return `${front}; ${sheet}${stacked}${trailer()}`;
+}
+/**
+ * The warning an OPEN Things dialog earns, wherever it is reported.
+ *
+ * FIELD-MEASURED (2026-08-27, controlled A/B on the maintainer's Mac): with a
+ * Repeat sheet left open, a write landed in the local database but Things Cloud
+ * did NOT attempt a sync — not on the write, and not when Things was brought
+ * back to the front. Dismissing the sheet released the queued sync immediately,
+ * with no further write. A stranded dialog is therefore not cosmetic: it holds
+ * the account's sync until someone dismisses it. Recorded in
+ * docs/things-app-oddities.md (the open-dialog sync gate).
+ */
+export const SYNC_GATE_WARNING = "while a dialog is open in Things the app stops sending changes to Things Cloud — anything " +
+    "written on this Mac stays on this Mac until the dialog is dismissed";
+//# sourceMappingURL=ui-state.js.map

package/dist/write/vectors/ui-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-state.js","sourceRoot":"","sources":["../../../src/write/vectors/ui-state.ts"],"names":[],"mappings":"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"}

package/dist/write/vectors/ui.d.ts

@@ -1,6 +1,7 @@
 import { type ThingsApiConfig } from "../../config.ts";
 import { type UiDriveAux } from "./ui-drag.ts";
-import type { UiPrimitive, UiStep, WriteVector } from "./types.ts";
+import { type UiSheetKind, type UiState } from "./ui-state.ts";
+import type { UiClearOutcome, UiPrimitive, UiStep, WriteVector } from "./types.ts";
 /**
  * Command-level primitives. Extends the recipe `UiPrimitive` set with the
  * INTERNAL sub-steps composite recipe steps decompose into: a `click-element`
@@ -12,7 +13,14 @@ import type { UiPrimitive, UiStep, WriteVector } from "./types.ts";
  */
 export type UiCommandPrimitive = UiPrimitive | "resolve-frame" | "click-point" | "sidebar-snapshot" | "sidebar-scroll" | "sidebar-drag" | "sidebar-held-drag"
 /** One modifier-bearing key event pair posted straight at the Things process (ui-chord.ts). */
- | "chord-post";
+ | "chord-post"
+/**
+ * The cleanup ladder's first rung: press the open dialog's own Cancel button
+ * (issue #620). Its own primitive rather than a `press` so a recipe's
+ * actuations and the cleanup's are never confused — in a trace, in a test, or
+ * in the completed-steps trail.
+ */
+ | "dismiss-dialog";
 /** A single primitive dispatch — one stable shape per primitive. */
 export interface UiCommand {
     primitive: UiCommandPrimitive;
@@ -38,6 +46,21 @@ export interface UiRunResult {
  * (CLAUDE.md safety rails — the production app is never a valid target).
  */
 export type UiRunner = (command: UiCommand, timeoutMs: number) => Promise<UiRunResult>;
+/**
+ * The IN-SCRIPT half of the per-step focus guard (issue #620).
+ *
+ * A synthetic keystroke is not addressed at an element — System Events hands it
+ * to whatever application owns the screen at that instant. So every script that
+ * types re-asserts, in the same osascript hop that will do the typing, that
+ * Things is still frontmost; the drive-level census (see {@link guardedRun})
+ * runs a moment earlier and cannot close the last few milliseconds. The
+ * assertion FAILS CLOSED and names the application that owns the screen
+ * instead — never the contents of its window.
+ *
+ * This is the cheapest possible check: one System Events property read, no
+ * sleeps, no polling (UI-automation determinism doctrine).
+ */
+export declare const AX_FOCUS_GUARD_HANDLERS = "on fgFrontApp()\n\tset frontName to \"\"\n\ttry\n\t\ttell application \"System Events\" to set frontName to (name of first application process whose frontmost is true) as text\n\tend try\n\treturn frontName\nend fgFrontApp\n\non fgAssertFront(what)\n\tset f to my fgFrontApp()\n\tif f is \"Things3\" then return true\n\tif f is \"\" then\n\t\terror \"refused to \" & what & \": the frontmost application could not be read, so there is no proof the keystrokes would reach Things \u2014 nothing was typed\"\n\tend if\n\terror \"refused to \" & what & \": \" & f & \" is frontmost, not Things \u2014 a keystroke goes to whatever owns the screen, so nothing was typed\"\nend fgAssertFront";
 /** resolve-element: does the element exist right now? Returns "true"/"false". */
 export declare function axResolveScript(path: string): string;
 /** press: AXPress the element. */
@@ -78,8 +101,25 @@ export declare function axPressScript(path: string): string;
  * 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.
+ *
+ * READ-BACK FIRST (issue #620 item 7): a field that ALREADY holds the requested
+ * value is left alone and the script returns {@link OK_ALREADY} — the whole
+ * keystroke class disappears for the defaults, which is most drives (the field
+ * incident died typing interval `1` into a field already showing `1`). The skip
+ * is proven by TWO reads a settle apart, because the one way a matching value
+ * can go stale is the UIC7 re-layout revert, which lands within that window; and
+ * whatever this decides, the pre-commit audit ({@link axAuditDialogScript})
+ * re-reads every control through its own address before the OK press, so a
+ * wrongly-skipped field cannot commit.
  */
 export declare function axSetValueScript(path: string, value: string, attempts?: number): string;
+/**
+ * What a typing primitive returns when it typed NOTHING because the field
+ * already held the requested value (issue #620 item 7). Distinct from "OK" so
+ * the drive can disclose the skip — and so a lab cell can assert that no
+ * keystroke hop fired.
+ */
+export declare const OK_ALREADY = "OK-ALREADY";
 /**
  * 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
@@ -421,7 +461,13 @@ export declare function axSelectHeadingRowScript(tablePath: string, ordinal: num
 export declare function axAssertEligibleScript(targetUuid: string, menuItemPath: string): string;
 /** activate: foreground Things (the fallback preamble step). */
 export declare function axActivateScript(): string;
-/** key: a space-separated keystroke spec (e.g. "down down return"). */
+/**
+ * key: a space-separated keystroke spec (e.g. "down down return").
+ *
+ * Frontmost-guarded in-script (issue #620): `key code`/`keystroke` reach
+ * whatever application owns the screen, so the script refuses — naming that
+ * application — rather than firing keys into someone else's window.
+ */
 export declare function axKeyScript(keys: string): string;
 /**
  * type-text: send literal text to whatever control holds focus (HXPC1). The
@@ -487,8 +533,40 @@ export declare function axRowCellFrameScript(tablePath: string, description: str
  * actually offered, so the caller learns what the app was willing to move to.
  */
 export declare function axPickerRowFrameScript(pickerPath: string, title: string): string;
-/** The abort keystroke sent to dismiss a half-open sheet/popover on failure. */
+/**
+ * The abort keystroke, sent ONLY from the audited cleanup ladder (issue #620)
+ * and only once that ladder has proven Things owns the screen. It is scoped to
+ * the Things process for readability, but scoping is not what makes it safe —
+ * a synthetic key goes to whatever is frontmost, which is why the script
+ * carries the same in-script frontmost assertion every other keystroke does.
+ */
 export declare function axAbortScript(): string;
+/**
+ * Dismiss the open dialog by PRESSING ITS OWN CANCEL BUTTON (issue #620).
+ *
+ * Preferred over Escape wherever it works, for two independent reasons: an
+ * AXPress is addressed at an ELEMENT, so it cannot leak into another
+ * application the way a keystroke can, and it works while Things is in the
+ * BACKGROUND — the cleanup never has to steal the user's focus to undo its own
+ * half-finished dialog. The button is addressed by its pinned English title,
+ * exactly like every other selector in this vector, and the dialog shell is
+ * resolved the same two ways the census resolves it (attached sheet, or the
+ * detached editor window Things presents when it is not frontmost).
+ *
+ * Returns "OK" after pressing, or a diagnostic ("NO-DIALOG" / "NO-CANCEL") the
+ * ladder falls through on — it never claims a dismissal; the caller re-reads
+ * the census to decide that.
+ */
+export declare function axCancelDialogScript(): string;
+/**
+ * The Cancel button's on-screen FRAME, resolved through the same addressed
+ * dialog-shell path the AXPress dismissal uses (issue #629). Feeds the pointer
+ * fallback: if `AXPress` on the button reports success and the dialog is still
+ * standing, a real click at the button's own AX-resolved centre is the next
+ * thing to try before discarding the window wholesale. The frame comes from the
+ * tree, never from a remembered coordinate, so a moved dialog fails closed.
+ */
+export declare function axCancelFrameScript(): string;
 /**
  * The PROVEN app-level clearance / relocation maneuver (SESSGATE, #480, live-host
  * recovery): close the front Things window — which takes an attached modal sheet
@@ -514,6 +592,37 @@ export declare function axCloseReopenActivateScript(): string;
  * command shape.
  */
 export declare function axSheetOpenScript(): string;
+/**
+ * The outcome of clearing a half-open dialog after a failed drive:
+ *   - "none"          — the census found no dialog open (nothing to clear);
+ *   - "dismissed"     — it is gone, and a fresh census CONFIRMED that;
+ *   - "cleared-blind" — the session was AX-blind (locked / off-Space), so no
+ *                       census and no keystroke can be trusted; the PROVEN
+ *                       app-level close+reopen ran to clear it (cannot be
+ *                       AX-confirmed, but the maneuver works blind — SESSGATE);
+ *   - "foreign"       — a dialog is open that this drive did not open, so it was
+ *                       LEFT ALONE (a cleanup must never dismiss the dialog the
+ *                       person at the keyboard opened after our failure);
+ *   - "may-remain"    — ours, and nothing in the ladder would close it
+ *                       (fail-closed: report it precisely, with the sync gate).
+ */
+export type ClearOutcome = UiClearOutcome;
+export interface ClearResult {
+    state: ClearOutcome;
+    /** How it was closed, for the trace and the disclosure. */
+    how?: "cancel-button" | "escape" | "window-close";
+    /** What the census identified as open at cleanup time. */
+    sheetKind?: UiSheetKind;
+    /** Who owned the screen when the cleanup started, when it was not Things. */
+    focusOwner?: string;
+    /**
+     * True when the cleanup ran WITHOUT a working window-state inspection (issue
+     * #629) — the dismissal and its proof came from addressed reads alone, so the
+     * outcome is real but the identity of what was dismissed was taken from what
+     * this drive had already observed rather than re-confirmed.
+     */
+    unverified?: boolean;
+}
 /**
  * resolve-frame: read the element's on-screen frame (top-left origin, points)
  * from the live AX tree and print "x y w h". Used by `click-element` to target
@@ -577,6 +686,29 @@ export declare function parseFrameCenter(stdout: string): {
     x: number;
     y: number;
 } | null;
+/**
+ * Read the live window/focus census through the shipped dispatch seam — the
+ * transport behind the `ui-state` diagnostic (src/ui-state.ts) and, in tests,
+ * behind any injected runner. READ-ONLY: the census clicks nothing, types
+ * nothing, and changes no state; see src/write/vectors/ui-state.ts.
+ */
+export declare function readLiveUiState(run?: UiRunner): Promise<UiState | null>;
+/**
+ * Judge one guard reading. Returns null to proceed, or the refusal sentence —
+ * which always names who owns the screen, because that is the one fact the
+ * person reading it cannot recover after the fact.
+ *
+ * Exported for the unit matrix: every branch here is a fail-closed decision
+ * about synthetic input, and each one is worth a test.
+ */
+export declare function judgeFocusGuard(state: UiState | null, expectedSheet: UiSheetKind | null, label: string): string | null;
+/**
+ * The cleanup disclosure (issue #620). Every branch states what is TRUE of the
+ * app right now, and — whenever a dialog may still be open — that Things Cloud
+ * sync is held until someone dismisses it, which is the consequence a caller
+ * cannot see and would otherwise discover hours later on another device.
+ */
+export declare function describeCleanup(clear: ClearResult): string;
 /** Compile one recipe step into its primitive command (no dispatch). */
 export declare function commandForStep(step: UiStep, targetUuid: string): UiCommand;
 /**