things-api 0.19.1 → 0.19.2

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

@@ -0,0 +1,157 @@
+/**
+ * The READ-ONLY window/focus census (issue #620, field report M1).
+ *
+ * One stable osascript shape answers four questions without touching anything —
+ * no click, no keystroke, no menu opened, no state changed:
+ *
+ *   - is a Things sheet/dialog open, and WHICH one (identified from its control
+ *     census, never from a localized title alone);
+ *   - is Things the frontmost application;
+ *   - who owns keyboard focus instead (application + element ROLE);
+ *   - could the frontmost surface be inspected at all (a secure system modal —
+ *     a macOS privacy/consent dialog — belongs to no application's
+ *     Accessibility tree, and that is reported as exactly that rather than
+ *     guessed at).
+ *
+ * It has three consumers, deliberately ONE shape for all of them:
+ *   1. the PER-STEP GUARD before every keystroke-class hop (ui.ts) — a keystroke
+ *      goes to whatever is frontmost, so typing while another app owns the
+ *      screen types into the void, or into someone else's window;
+ *   2. the PRE-CLEANUP oracle — Escape is itself a keystroke, so the abort path
+ *      must know who would receive it before sending it;
+ *   3. the `ui-state` diagnostic (and `things doctor --ui-state`).
+ *
+ * PRIVACY: the census emits ROLE COUNTS and element ROLES only — never a
+ * control's value, title or description, and never a window title. A Things
+ * sheet routinely displays the user's own to-do text, and a diagnostic that
+ * gets pasted into a bug report must not carry it.
+ */
+import type { UiCommand, UiRunResult } from "./ui.ts";
+/**
+ * Which dialog is up, decided by STRUCTURE (the control census measured in
+ * docs/lab/rdlg1-323-repeat-dialog-census.md §2.1) rather than by a localized
+ * string:
+ *
+ *   - `repeat`      — the Repeat sheet: exactly two checkboxes, exactly one
+ *                     direct pop-up button (the frequency), exactly two buttons
+ *                     (OK / Cancel), no direct text field, and one cadence group
+ *                     carrying its own field/pop-up. That shape holds in every
+ *                     mode of the 3.23 dialog and in both of its forms (attached
+ *                     sheet when Things is frontmost, detached editor window when
+ *                     it is not), and no other Things sheet presents it.
+ *   - `move-picker` — the Move… project picker, identified POSITIVELY by its own
+ *                     `AXIdentifier` prefix (`MovePopUpDialog-`) — the same
+ *                     identity check the picker-row resolver makes.
+ *   - `other`       — something modal is up that is neither of those.
+ *   - `none`        — no attached sheet and no detached editor window.
+ */
+export type UiSheetKind = "none" | "repeat" | "move-picker" | "other";
+/** How the dialog presents: attached to the standard window, or detached (Things backgrounded). */
+export type UiSheetForm = "none" | "attached" | "detached";
+/**
+ * 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 declare const AX_DIALOG_SHELL_SNIPPET = "\t\tset shellRef to missing value\n\t\tset sheetForm to \"none\"\n\t\tset sheetDepth to 0\n\t\ttry\n\t\t\t-- positional-ok: the one attached sheet a window can present, which is\n\t\t\t-- the BOTTOM of any stack; the walk below climbs to the top.\n\t\t\tset shellRef to sheet 1 of (first window whose subrole is \"AXStandardWindow\")\n\t\t\tset sheetForm to \"attached\"\n\t\t\tset sheetDepth to 1\n\t\tend try\n\t\tif shellRef is missing value then\n\t\t\ttry\n\t\t\t\tset dws to (windows whose subrole is \"AXUnknown\" and size is not {40, 40})\n\t\t\t\tif (count of dws) > 0 then\n\t\t\t\t\tset shellRef to item 1 of dws\n\t\t\t\t\tset sheetForm to \"detached\"\n\t\t\t\t\tset sheetDepth to 1\n\t\t\t\tend if\n\t\t\tend try\n\t\tend if\n\t\tif shellRef is not missing value then\n\t\t\trepeat 6 times\n\t\t\t\tset nested to missing value\n\t\t\t\ttry\n\t\t\t\t\tif (exists sheet 1 of shellRef) then set nested to sheet 1 of shellRef\n\t\t\t\tend try\n\t\t\t\tif nested is missing value then exit repeat\n\t\t\t\tset shellRef to nested\n\t\t\t\tset sheetDepth to sheetDepth + 1\n\t\t\tend repeat\n\t\tend if";
+/** Who owns keyboard focus. Role only — never the element's value or title (see PRIVACY). */
+export interface UiFocusOwner {
+    /** The frontmost application's process name (e.g. "Things3"). */
+    app: string;
+    /** The focused element's `AXRole`, or "" when the tree would not answer. */
+    role: string;
+    /** The focused element's `AXSubrole`, or null when it has none. */
+    subrole: string | null;
+}
+export interface UiState {
+    /** Is the Things process present at all? */
+    thingsRunning: boolean;
+    /** Is Things the frontmost application — the surface a keystroke would reach? */
+    thingsFrontmost: boolean;
+    /** The frontmost application's process name; null when it could not be read. */
+    frontmostApp: string | null;
+    /** Is a modal sheet / detached editor open in Things? */
+    sheetOpen: boolean;
+    /** What the dialog IN FRONT is — the innermost of a stack (see {@link AX_DIALOG_SHELL_SNIPPET}). */
+    sheetKind: UiSheetKind;
+    sheetForm: UiSheetForm;
+    /**
+     * How many dialogs are stacked (0 when none, 1 for the ordinary case). Sheets
+     * nest as children of the sheet below and dismiss strictly LIFO, so a depth
+     * above 1 means one dismissal is not enough — and that the thing in front is
+     * NOT the dialog a drive opened (MODALX1 §6).
+     */
+    sheetDepth: number;
+    /**
+     * The open dialog's control census — role COUNTS only, the evidence behind
+     * `sheetKind` (e.g. `cb:2 pu:1 bt:2 gp:1 tf:0`). Null when no dialog is open.
+     */
+    sheetControls: string | null;
+    /** Who owns keyboard focus; null when nothing could be read. */
+    focusOwner: UiFocusOwner | null;
+    /**
+     * False when the frontmost surface could not be walked at all — the signature
+     * of a SECURE SYSTEM MODAL (a macOS privacy/consent dialog), which belongs to
+     * no application's Accessibility tree. Everything else in the census is then
+     * "what could still be proven", never a guess.
+     */
+    inspectable: boolean;
+}
+/** A recognizable token in the script so a test runner can key off the ui-state command. */
+export declare const UI_STATE_MARKER = "-- ui-state census (read-only)";
+/** The label every ui-state dispatch carries (one stable command shape). */
+export declare const UI_STATE_LABEL = "read the window and focus state";
+/** The Things application's process name — the frontmost value that means "us". */
+export declare const THINGS_PROCESS = "Things3";
+/**
+ * The census script. Every read is wrapped: a surface that will not answer
+ * degrades that ONE field rather than failing the whole census, because the
+ * cases this exists for — a foreign modal, an AX-blind session — are exactly
+ * the cases where half the tree is unreadable.
+ */
+export declare function axUiStateScript(): string;
+/**
+ * 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 declare function parseUiState(stdout: string): UiState | null;
+/**
+ * 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).
+ */
+export declare function readUiState(run: (command: UiCommand, timeoutMs: number) => Promise<UiRunResult>, timeoutMs: number): Promise<UiState | null>;
+/**
+ * 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 declare function describeFocusOwner(state: UiState | null): string;
+/** A one-line human summary of the census, for a diagnostic line or a warning. */
+export declare function describeUiState(state: UiState): string;
+/**
+ * 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 declare const SYNC_GATE_WARNING: string;

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

@@ -0,0 +1,237 @@
+/** 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`;
+/** 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. Every read is wrapped: a surface that will not answer
+ * degrades that ONE field rather than failing the whole census, because the
+ * cases this exists for — a foreign modal, an AX-blind session — are exactly
+ * the cases where half the tree is unreadable.
+ */
+export function axUiStateScript() {
+    return `${UI_STATE_MARKER}
+set frontName to ""
+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 ""
+tell application "System Events"
+	try
+		set fp to first application process whose frontmost is true
+		set frontName to (name of fp) as text
+		try
+			set fe to value of attribute "AXFocusedUIElement" of fp
+			set focusRole to (role of fe) as text
+			try
+				set focusSub to (subrole of fe) as text
+			end try
+		on error
+			set canInspect to false
+		end try
+	on error
+		set canInspect to false
+	end try
+	try
+		if (exists application process "${THINGS_PROCESS}") then set thingsRunning to true
+	end try
+end tell
+if thingsRunning then
+	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 if
+return "front=" & frontName & linefeed & "running=" & thingsRunning & linefeed & "form=" & sheetForm & linefeed & "depth=" & sheetDepth & linefeed & "kind=" & sheetKind & linefeed & "census=" & census & linefeed & "role=" & focusRole & linefeed & "subrole=" & focusSub & linefeed & "inspectable=" & canInspect`;
+}
+/**
+ * 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 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") ?? "";
+    const subrole = fields.get("subrole") ?? "";
+    const census = fields.get("census") ?? "";
+    const depth = Number(fields.get("depth") ?? "0");
+    return {
+        thingsRunning: fields.get("running") === "true",
+        thingsFrontmost: frontmostApp === THINGS_PROCESS,
+        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",
+    };
+}
+/**
+ * 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).
+ */
+export async function readUiState(run, timeoutMs) {
+    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";
+    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. */
+export function describeUiState(state) {
+    const front = state.thingsFrontmost
+        ? "Things is frontmost"
+        : `${state.frontmostApp ?? "an unidentified application"} is frontmost`;
+    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}`;
+}
+/**
+ * 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,31 @@ 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 PROVEN app-level clearance / relocation maneuver (SESSGATE, #480, live-host
  * recovery): close the front Things window — which takes an attached modal sheet
@@ -514,6 +583,30 @@ 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;
+}
 /**
  * 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 +670,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;
 /**