things-api 0.19.0 → 0.19.2

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`
@@ -10,7 +11,16 @@ import type { UiPrimitive, UiStep, WriteVector } from "./types.ts";
  * every subprocess call behind the injectable `run` seam makes the
  * orchestration unit-testable without a GUI.
  */
-export type UiCommandPrimitive = UiPrimitive | "resolve-frame" | "click-point" | "sidebar-snapshot" | "sidebar-scroll" | "sidebar-drag" | "sidebar-held-drag";
+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"
+/**
+ * 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;
@@ -36,23 +46,220 @@ 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. */
 export declare function axPressScript(path: string): string;
 /**
  * set-field-value: enter a value into the dialog's numeric text field (interval,
- * ends-count, start-days-earlier). It FOCUSES the field, selects all, TYPES the
- * value, and Tabs to commit — because `set value of <field>` writes the field's
- * displayed text WITHOUT firing the edit, so the app's binding keeps the old
- * number (the field shows "5" but the rule stays interval 1 — a silent no-op
- * exactly like `set value` on a pop-up, UIC6; it went unnoticed while every base
- * case used the default interval 1). Real keystrokes fire the change the binding
- * needs; Tab (not Return, which would fire the default OK button) commits and
- * moves focus. Foreground-bound (keystrokes reach the frontmost app) — the
- * reveal/activate preamble puts Things there. One stable command shape.
+ * ends-count, start-days-earlier) — and into the Move… picker's filter field. It
+ * FOCUSES the field, TYPES the value, and Tabs to commit — because
+ * `set value of <field>` writes the field's displayed text WITHOUT firing the
+ * edit, so the app's binding keeps the old number (the field shows "5" but the
+ * rule stays interval 1 — a silent no-op exactly like `set value` on a pop-up,
+ * UIC6; it went unnoticed while every base case used the default interval 1).
+ * Real keystrokes fire the change the binding needs; Tab (not Return, which would
+ * fire the default OK button) commits and moves focus. Foreground-bound
+ * (keystrokes reach the frontmost app) — the reveal/activate preamble puts Things
+ * there. One stable command shape.
+ *
+ * NO SELECT-ALL KEYSTROKE (BEEP1, 2026-08-25, docs/lab/beep1-numeric-field-beep.md).
+ * The primitive used to send ⌘A before typing, and that ONE keystroke was the
+ * audible macOS alert beep every numeric-field drive fired on the live host:
+ * Things' `Edit ▸ Select All` menu item exists and is DISABLED while the Repeat
+ * sheet is up, AppKit dispatches ⌘A as a menu key equivalent FIRST, the disabled
+ * item swallows it, nothing handles it → NSBeep. It is a menu-dispatch fact, not
+ * a focus race: the beep survives a verified first responder and a 1.5 s settle,
+ * while Tab and the digits themselves are silent. ⌘A was also REDUNDANT —
+ * `set focused of tf to true` installs the field editor with the ENTIRE content
+ * selected (measured: `AXSelectedTextRange` length goes 0 → the full value
+ * length, on both a 1- and a 2-character value), so typing replaces the old value
+ * outright, including the shrinking case (12 → 3) that a stale caret would have
+ * corrupted into "123". Dropping the keystroke is therefore silent AND correct on
+ * all three fields.
+ *
+ * CLOSED-LOOP (determinism doctrine): type, Tab-commit, then READ THE FIELD BACK
+ * and retry if it did not hold — the interval field, when it is the first numeric
+ * field after a frequency/type switch, races the dialog's group re-layout and
+ * reverts to 1 (UIC7, oddities §8l). Re-focus + re-type after a settle lands it
+ * once the re-layout has finished, and the re-focus re-selects the whole value,
+ * so a retry starts from a clean field without ⌘A. Fail-closed (an `error`, i.e.
+ * a transport failure the pipeline re-verifies) if it never holds — the
+ * create/reschedule delta's rule assertion is the final DB-level authority.
+ *
+ * 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
+ * sits on (HXPC1, docs/lab/hxpc1-picker-assert.md §A; hardened by CGRD1,
+ * docs/lab/cgrd1-precommit-audit.md §A).
+ *
+ * Both fields used to be spelled `text field 1 of group 1`, which is the same
+ * control at different moments. Measured on Things 3.23 (build 32300036):
+ *
+ *   Ends: never   → group text fields = 1  ·  tf1 = interval  @[311,283]
+ *   Ends: after N → group text fields = 2  ·  tf1 = COUNT     @[402,372]
+ *                                             tf2 = interval  @[311,283]
+ *
+ * i.e. selecting the "after" bound INSERTS the count ahead of the interval. The
+ * create path got away with it by driving the interval while it was still the
+ * sole field, but a RESCHEDULE opens the dialog pre-populated: a rule that
+ * already ends after N presents both fields from the first step, so the interval
+ * drive wrote the requested interval into the count field, the count drive then
+ * overwrote it, and the interval silently never changed.
+ *
+ * The addresses are the {@link AX_CADENCE_HANDLERS} laws — POSITIVE label-row
+ * matches wherever the app offers a label to match, a uniqueness check where it
+ * does not, and a fail-closed refusal naming the whole numeric-field inventory
+ * otherwise. The write itself is the {@link axSetValueScript} closed loop —
+ * focus, type, Tab-commit, read back, bounded retries — and, like it, sends NO
+ * select-all keystroke: the ⌘A that used to open it is the macOS alert beep
+ * (BEEP1, docs/lab/beep1-numeric-field-beep.md), and focusing the field already
+ * selects its whole content.
+ *
+ * The read-back this loop performs is SELF-REFERENTIAL by construction — it
+ * re-reads the field it addressed, so it can only prove the keystrokes landed
+ * where they were aimed, never that they were aimed at the right control. The
+ * PRE-COMMIT AUDIT ({@link axAuditDialogScript}) is what closes that: it re-reads
+ * every control through these same handlers just before the OK press.
+ */
+export declare function axSetGroupNumberScript(groupPath: string, target: "interval" | "ends-count", value: string, attempts?: number, rowTolerance?: number): string;
+/**
+ * set-row-field: drive a Repeat-dialog text field addressed by the pinned English
+ * LABEL sharing its row — the same discrimination law as
+ * {@link axSetGroupNumberScript}, applied to a field that lives on the dialog
+ * SHELL rather than in the cadence group.
+ *
+ * Its one caller is the "and start [N] days earlier" offset the "Add deadlines"
+ * checkbox reveals, which shipped as `text field 1` of the shell. That address
+ * was the HXPC1 error class exactly: a value-bearing text field picked by index
+ * out of a STATE-DEPENDENT tree (the field does not exist at all until the
+ * checkbox is ticked), verified only by re-reading the same index it wrote. It
+ * happened to be right on 3.23 — measured, the shell carries 0 direct text fields
+ * with deadlines off and exactly 1 with them on, whether or not reminders are also
+ * on (CGRD1 §B census) — but nothing in the address said so, and an AX tree is an
+ * undocumented private surface that may add a second field in any release.
+ *
+ * The label anchor is `days earlier` (y=413 against the field's y=409, CGRD1 §B).
+ * A missing label, or anything other than exactly one field on its row, FAILS
+ * CLOSED naming the shell's whole text-field inventory. The write is the
+ * {@link axSetValueScript} closed loop.
+ */
+export declare function axSetRowFieldScript(containerPath: string, rowLabel: string, value: string, attempts?: number, rowTolerance?: number): string;
+/**
+ * ONE control the PRE-COMMIT DIALOG AUDIT re-reads, in the form the generator
+ * needs: a resolved element path (the shell / dialog-shape disjunctions are
+ * settled by the driver before the script is built) plus the value(s) the drive
+ * intended for it.
+ */
+export interface AuditScriptControl {
+    /** Human name of the control, as the mismatch report should say it. */
+    label: string;
+    kind: "popup" | "checkbox" | "group-number" | "row-field" | "weekdays" | "occurrence-popup";
+    /** popup / checkbox / occurrence-popup: the resolved element path. */
+    path?: string;
+    /** group-number: which of the cadence group's numeric fields. */
+    numberTarget?: "interval" | "ends-count";
+    /** row-field: the pinned English label sharing the field's row. */
+    rowLabel?: string;
+    /** weekdays: the group pop-up index of the first weekday row (shape-selected). */
+    weekdayBase?: number;
+    /** The accepted observed values — ANY one satisfies (the singular/plural pair). */
+    expected: string[];
+    /** How the intended value should READ in the report ("checked", not "1"). */
+    expectedLabel?: string;
+}
+/** The resolved audit the {@link axAuditDialogScript} generator compiles. */
+export interface AuditScriptSpec {
+    /** The resolved dialog shell (attached sheet or detached editor window). */
+    shell: string;
+    /** The resolved cadence group inside that shell. */
+    group: string;
+    controls: AuditScriptControl[];
+}
+/**
+ * audit-dialog: RE-READ EVERY CONTROL THIS DRIVE SET, through each control's own
+ * discriminated address, and refuse to commit if any one of them does not hold
+ * the value the drive intended.
+ *
+ * This exists because a per-step read-back is SELF-REFERENTIAL. Every setter here
+ * confirms its write by re-reading the element it addressed, so it proves the
+ * keystrokes landed where they were aimed — and nothing else. The #589 wrong-field
+ * write reported OK for exactly that reason: the interval drive typed into the
+ * ends-count field, then read the ends-count field back and found its own number
+ * sitting there. The address was wrong; a read-back through the same address
+ * cannot see that.
+ *
+ * The audit is the outside view. It is assembled from the recipe's OWN step list
+ * (so no control the recipe drives can be left out of the audit by omission) and
+ * runs as the last step before the OK press, comparing the dialog's complete
+ * intended state against what the dialog actually shows: frequency, the
+ * after-completion cadence unit, interval, ends bound and its count, the
+ * deadline/reminder checkboxes, the start-days-earlier offset, the weekday set,
+ * the monthly/yearly anchor pop-ups and the 3.23 first-occurrence pop-up. A
+ * mismatch is an `error` naming EVERY differing control with both values, which
+ * aborts the drive fail-closed BEFORE the commit and runs the standard clean-abort
+ * path — nothing reaches the database.
+ *
+ * Deterministic throughout: the cadence group is settled on its own shape
+ * signature (the BEEP1 two-agreeing-reads gate), never on a sleep, and every field
+ * is found by its label row rather than by index ({@link AX_CADENCE_HANDLERS}).
+ *
+ * The dialog's three `AXDateTimeArea` controls are audited separately — their
+ * values are NSDates no System Events read can reach, so they ride
+ * {@link axAuditDateAreasScript} through the same ObjC bridge that writes them.
+ */
+export declare function axAuditDialogScript(spec: AuditScriptSpec, rowTolerance?: number): string;
+/** ONE date/time area the pre-commit audit re-reads through the ObjC bridge. */
+export interface AuditDateArea {
+    /** Human name of the control, as the mismatch report should say it. */
+    label: string;
+    target: "next" | "ends" | "reminder";
+    /** The spec the drive wrote: `date:YYYY-MM-DD` or `time:HH:mm`. */
+    spec: string;
+}
+/**
+ * The pre-commit audit's DATE-AREA leg. The dialog's first-occurrence, ends-on and
+ * reminder controls are `AXDateTimeArea`s whose value is an NSDate — unreachable
+ * from System Events — so they are re-read through the SAME ObjC bridge, the same
+ * shell-scoped walk and the SAME deterministic `pick` discriminator that
+ * {@link axSetDateTimeScript} writes them through. A control the audit cannot find,
+ * or one holding a different date/time, throws naming every area the dialog does
+ * present (y-position + time-of-day), so the drive aborts before the OK press.
+ */
+export declare function axAuditDateAreasScript(areas: AuditDateArea[]): string;
 /**
  * ensure-checkbox: converge a dialog checkbox to a target state through a
  * DETERMINISTIC CLOSED LOOP (RRD1, determinism doctrine) — never a blind toggle.
@@ -140,6 +347,32 @@ export declare function axProbeDialogShapeScript(groupPath: string, rowTolerance
  * (the fail-closed read-back the ANCH2/YANCH1 date drives established).
  */
 export declare function axSelectNextOccurrenceScript(popupPath: string, isoDate: string, maxLevels?: number): string;
+/**
+ * settle-occurrences: let the 3.23 `Next:` pop-up ABSORB the rule change the
+ * preceding steps made, before the drive touches the dialog again (NEXTPOP1).
+ *
+ * MEASURED (golden-v4 / Things 3.23, `research-nextpop1.sh` DIAG3/DIAG4): the
+ * dialog recomputes the first-occurrence pop-up — its displayed value AND the
+ * menu of occurrences behind it — ASYNCHRONOUSLY. After the yearly anchor was
+ * moved from Aug 6 to Aug 20 the control flipped at **t+0.4s** with nothing else
+ * driven; when the very next step (the "Add deadlines" checkbox) was pressed
+ * inside that window instead, the control NEVER caught up — it still read
+ * `Thu, Aug 6, 2026`, and its menu still enumerated the Aug-6 series, six
+ * seconds later. A cancelled recompute does not retry.
+ *
+ * That is what made every deadlined monthly/yearly promote fail closed on 3.23:
+ * the anchor drive is followed immediately by the deadline controls, so by the
+ * time `select-next-occurrence` opened the menu it was the SEED's series, and
+ * the requested date — the rule's own first due date — was genuinely not in it
+ * (VMRES1 §4.3, reproduced and explained in NEXTPOP1).
+ *
+ * The wait is closed-loop in the direction that matters: it exits the moment the
+ * control MOVES, which is the case that needs waiting for. When the rule change
+ * did not move the first occurrence there is nothing to observe, so the budget
+ * bounds it — deliberately over-cautious, since the cost is a fraction of a
+ * second and the alternative is a series that starts on the wrong date.
+ */
+export declare function axSettleOccurrencesScript(popupPath: string, budgetMs?: number, pollMs?: number): string;
 /**
  * converge-weekdays: drive the weekly dialog's weekday ROWS onto an exact target
  * set through a deterministic closed loop (RDLG2 — the RRD1 fix).
@@ -228,10 +461,103 @@ 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;
-/** The abort keystroke sent to dismiss a half-open sheet/popover on failure. */
+/**
+ * type-text: send literal text to whatever control holds focus (HXPC1). The
+ * Move… picker focuses its own filter field the instant it opens, and that field
+ * is NOT addressable as a direct child of the picker window — so there is no
+ * element to hand `set-value`, whose select-all + Tab commit would be wrong for a
+ * search field regardless (a popover filter has no next key view for Tab to move
+ * to). Unlike {@link axKeyScript}, which splits its spec on whitespace and would
+ * drop the spaces out of a multi-word project title, this sends the string as
+ * ONE keystroke. It is deliberately not self-verifying: the `click-picker-row`
+ * step that follows resolves the destination row by name and fails closed when
+ * the filter did not produce it, so a keystroke that landed elsewhere can never
+ * be committed. One stable command shape.
+ */
+export declare function axTypeTextScript(text: string): string;
+/**
+ * resolve-frame for a control nested inside a CONTENT-TABLE ROW: walk the
+ * table's rows → cells → cell children and return the frame of the one whose
+ * `AXDescription` equals `description` (HXPC1, docs/lab/hxpc1-picker-assert.md
+ * §B0). Same "x y w h" contract as {@link axFrameScript}.
+ *
+ * This exists because the heading row's `…` button — the only content-row
+ * control that carries its own title (`"More. <heading title>"`, the HEADXPROJ
+ * enabler) — sits at `UI element N of cell 1 of row M of the table`, and
+ * `first UI element of <table> whose description is …` searches the table's
+ * DIRECT children only. Those are the rows, which carry no description, so the
+ * shipped one-level spelling matched nothing and the ellipsis drives
+ * (`project.move-heading-to-project`, `project.dissolve-heading`) died at their
+ * own frame resolution before any click — measured on Things 3.23 against a
+ * heading whose button the raw Accessibility API resolves at the same instant.
+ * The row/cell indices are never guessed: every row is walked and the match is
+ * exact, so a heading whose title changed under us fails closed by name.
+ */
+export declare function axRowCellFrameScript(tablePath: string, description: string): string;
+/**
+ * resolve-frame for the Move… picker ROW carrying an exact project title — the
+ * step that replaced the recipe's blind Return (HXPC1,
+ * docs/lab/hxpc1-picker-assert.md §B).
+ *
+ * The picker exposes no `AXSelected` / `AXFocused` / `AXHighlighted` on any row
+ * (measured — only its filter field is focused), so there is nothing to read
+ * back from a keyboard commit and no way to assert what Return would take. What
+ * it does expose is one `AXUnknown` per row whose `AXDescription` IS the project
+ * title, and — whenever the filter holds text — a trailing
+ * `New Project "<typed text>"` row that CREATES a project when committed. That
+ * row is what the blind Return took whenever the destination was missing from
+ * the picker, which an ordinary database-resolved destination reaches: a
+ * COMPLETED or CANCELED project appears nowhere in the picker, so the drive
+ * minted a second project of the same title and moved the heading into it
+ * (measured 3.23: projects 14 → 15, heading re-parented to the new row).
+ *
+ * So the commit is addressed instead of guessed. The script requires:
+ *   - the picker to be the window it claims (its `AXIdentifier` begins
+ *     `MovePopUpDialog-`) — a positive identity check, so a different detached
+ *     window can never be clicked into;
+ *   - EXACTLY ONE row whose description equals the destination title (the
+ *     New-Project row's description is the quoted form, so an exact match cannot
+ *     hit it);
+ *   - that row's centre to lie inside the picker's own scroll area — the CNCAC1
+ *     off-screen hazard, where a row scrolled past the fold still resolves a
+ *     frame and a click at it lands on the desktop.
+ * Any miss FAILS CLOSED naming the destination and listing every row the picker
+ * actually offered, so the caller learns what the app was willing to move to.
+ */
+export declare function axPickerRowFrameScript(pickerPath: string, title: string): string;
+/**
+ * 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
@@ -257,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
@@ -320,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;
 /**