things-api 0.19.2 → 0.19.3

package/README.md

@@ -4,7 +4,7 @@
 
 A typed TypeScript library + CLI (`things`) for programmatic interaction with [Things 3](https://culturedcode.com/things/) by Cultured Code.
 
-**Status: read + write + MCP layers live and published to npm (v0.19.2 — see [CHANGELOG.md](CHANGELOG.md)).** Reads go straight to the local SQLite database (UI-exact Today ordering, sidebar-grouped Anytime/Someday with container-status cascade, decoded repeat rules, occurrence projections); writes run a verified pipeline over four write vectors — two lab-validated headless surfaces (the URL scheme + AppleScript) and two opt-in surfaces (Apple Shortcuts and an Accessibility-driven GUI vector) — with hazard guards, disruption-tier policy, a JSONL audit trail, batch mode, audit-replay undo (transactional across compound operations), full project lifecycle (complete/cancel/reopen/restore), heading rename/archive/unarchive with children policies, container detach, granular stateful checklists, tag hierarchy management incl. un-nesting, completion/creation backdating, Logbook imports, tiered fuzzy name resolution (uuid prefixes, `things:///show?id=` share links), and kind-neutral in-place reordering within any container or view (one `things reorder <refs…> [--start|--end|--before|--after] --in <target>` verb — Today/Evening, a project, an area, a heading's children, someday, inbox — plus `project move-heading` for the headings themselves and `area reorder` for the sidebar). The Apple Shortcuts surface is wired for the two headless capabilities nothing else can do: creating a heading in an existing project (`things project add-heading`) and clearing a reminder from a date-scheduled item (`things todo clear-reminder`). Both run through bundled proxy shortcuts (`things setup`) and are gated on their presence. The fourth vector — the Accessibility-driven GUI vector — is off by default and drives the local Things app to reach transforms that exist on no scriptable surface (repeat-rule editing on existing to-dos and projects, convert-to-project, sidebar area reorder); see [Accessibility GUI vector](#accessibility-gui-vector-optional-off-by-default) below. Single-item permanent delete stays interactive-only (its macOS consent has no always-allow) and is out of the headless pipeline. See [docs/design/](docs/design/) for the architecture and VM-lab design, [docs/lab/](docs/lab/harness.md) for the probe harness and campaign results the write layer is grounded in, and [docs/atlas/](docs/atlas/schema-v26.md) for the database↔UI map.
+**Status: read + write + MCP layers live and published to npm (v0.19.3 — see [CHANGELOG.md](CHANGELOG.md)).** Reads go straight to the local SQLite database (UI-exact Today ordering, sidebar-grouped Anytime/Someday with container-status cascade, decoded repeat rules, occurrence projections); writes run a verified pipeline over four write vectors — two lab-validated headless surfaces (the URL scheme + AppleScript) and two opt-in surfaces (Apple Shortcuts and an Accessibility-driven GUI vector) — with hazard guards, disruption-tier policy, a JSONL audit trail, batch mode, audit-replay undo (transactional across compound operations), full project lifecycle (complete/cancel/reopen/restore), heading rename/archive/unarchive with children policies, container detach, granular stateful checklists, tag hierarchy management incl. un-nesting, completion/creation backdating, Logbook imports, tiered fuzzy name resolution (uuid prefixes, `things:///show?id=` share links), and kind-neutral in-place reordering within any container or view (one `things reorder <refs…> [--start|--end|--before|--after] --in <target>` verb — Today/Evening, a project, an area, a heading's children, someday, inbox — plus `project move-heading` for the headings themselves and `area reorder` for the sidebar). The Apple Shortcuts surface is wired for the two headless capabilities nothing else can do: creating a heading in an existing project (`things project add-heading`) and clearing a reminder from a date-scheduled item (`things todo clear-reminder`). Both run through bundled proxy shortcuts (`things setup`) and are gated on their presence. The fourth vector — the Accessibility-driven GUI vector — is off by default and drives the local Things app to reach transforms that exist on no scriptable surface (repeat-rule editing on existing to-dos and projects, convert-to-project, sidebar area reorder); see [Accessibility GUI vector](#accessibility-gui-vector-optional-off-by-default) below. Single-item permanent delete stays interactive-only (its macOS consent has no always-allow) and is out of the headless pipeline. See [docs/design/](docs/design/) for the architecture and VM-lab design, [docs/lab/](docs/lab/harness.md) for the probe harness and campaign results the write layer is grounded in, and [docs/atlas/](docs/atlas/schema-v26.md) for the database↔UI map.
 
 ```sh
 things today --json                # read: your Today list, Evening split, UI order

package/dist/contracts.d.ts

@@ -14,7 +14,7 @@ export declare const API_VERSION = 1;
  * Package version, surfaced by `things --version` and the MCP serverInfo.
  * Kept in lockstep with package.json by a contract test.
  */
-export declare const PKG_VERSION = "0.19.2";
+export declare const PKG_VERSION = "0.19.3";
 /**
  * Stable exit-code contract for the `things` CLI (mirrored by MCP error
  * codes). Part of the public API surface consumed by agents and scripts —

package/dist/contracts.js

@@ -13,7 +13,7 @@ export const API_VERSION = 1;
  * Package version, surfaced by `things --version` and the MCP serverInfo.
  * Kept in lockstep with package.json by a contract test.
  */
-export const PKG_VERSION = "0.19.2";
+export const PKG_VERSION = "0.19.3";
 /**
  * Stable exit-code contract for the `things` CLI (mirrored by MCP error
  * codes). Part of the public API surface consumed by agents and scripts —

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export { diagnose } from "./diagnose.ts";
 export type { DiagnoseOptions, DiagnoseReport, DiagnoseResult } from "./diagnose.ts";
 export { opResult } from "./op-result.ts";
 export { readUiStateReport, uiStateLines } from "./ui-state.ts";
-export type { UiFocusOwner, UiSheetForm, UiSheetKind, UiState, UiStateDeps, UiStateReport, } from "./ui-state.ts";
+export type { UiFocusOwner, UiProbe, UiSheetForm, UiSheetKind, UiState, UiStateDeps, UiStateReport, } from "./ui-state.ts";
 export type { OpResultData, OpResultOptions, OpResultStatus } from "./op-result.ts";
 export { probeAutomation } from "./write/automation-probe.ts";
 export type { AutomationProbeDeps, AutomationProbeResult, AutomationProbeStatus, } from "./write/automation-probe.ts";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAmBzC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAUhE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAM9D,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAOhC,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,+EAA+E;AAC/E,+EAA+E;AAC/E,uEAAuE;AACvE,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA6BtF,8EAA8E;AAC9E,gEAAgE;AAChE,mDAAmD;AACnD,OAAO,EACL,eAAe,EACf,cAAc,EACd,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AAoCnC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,iFAAiF;AACjF,8EAA8E;AAC9E,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AASlG,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAQ/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AASpF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAoB9D,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AASvE,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D,iFAAiF;AACjF,yEAAyE;AACzE,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,EACT,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAM/B,gFAAgF;AAChF,+EAA+E;AAC/E,uEAAuE;AACvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,gFAAgF;AAChF,4EAA4E;AAC5E,oDAAoD;AACpD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAG9D,iFAAiF;AACjF,wEAAwE;AACxE,kCAAkC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAGvD,kEAAkE;AAClE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGzF,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,yEAAyE;AACzE,+DAA+D;AAC/D,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,uBAAuB,EACvB,uBAAuB,EACvB,aAAa,EACb,uBAAuB,EACvB,cAAc,EACd,cAAc,EACd,eAAe,EACf,cAAc,EACd,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAoB7B,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,iBAAiB,EACjB,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,aAAa,EACb,QAAQ,EACR,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAaxB,8EAA8E;AAC9E,4EAA4E;AAC5E,4EAA4E;AAC5E,2EAA2E;AAC3E,8EAA8E;AAE9E,2EAA2E;AAC3E,cAAc,mBAAmB,CAAC;AAElC,yDAAyD;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AACzB,iFAAiF;AACjF,2EAA2E;AAC3E,4DAA4D;AAC5D,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACrE,+EAA+E;AAC/E,8EAA8E;AAC9E,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAIvD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,4EAA4E;AAC5E,+EAA+E;AAC/E,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG7E,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEjF,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMnF,0DAA0D;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AActD,4EAA4E;AAC5E,mEAAmE;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,gEAAgE;AAChE,yCAAyC;AACzC,OAAO,EACL,UAAU,EACV,OAAO,EACP,eAAe,EACf,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,SAAS,EACT,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAgBzB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAWnF,+EAA+E;AAC/E,4EAA4E;AAC5E,4EAA4E;AAC5E,iFAAiF;AACjF,mEAAmE;AACnE,OAAO,EACL,aAAa,EACb,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,KAAK,EACL,WAAW,EACX,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAWtC,MAAM,UAAU,aAAa;IAC3B,OAAO,MAAM,CAAC,iBAAiB,CAAC,CAAC;AACnC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/ui-state.d.ts

@@ -16,7 +16,7 @@
  */
 import { type UiCapability } from "./capability.ts";
 import { type UiState } from "./write/vectors/ui-state.ts";
-export type { UiFocusOwner, UiSheetForm, UiSheetKind, UiState } from "./write/vectors/ui-state.ts";
+export type { UiFocusOwner, UiProbe, UiSheetForm, UiSheetKind, UiState, } from "./write/vectors/ui-state.ts";
 export interface UiStateReport {
     /** Could the screen be read at all on this machine? */
     available: boolean;

package/dist/ui-state.js

@@ -15,7 +15,7 @@
  * surface may raise a consent dialog outside the two setup ceremonies.
  */
 import { uiAllowed, uiCapability as uiCapabilityDefault } from "./capability.js";
-import { describeUiState, SYNC_GATE_WARNING } from "./write/vectors/ui-state.js";
+import { describeUiState, describeUnprovenProbes, SYNC_GATE_WARNING, } from "./write/vectors/ui-state.js";
 import { readLiveUiState } from "./write/vectors/ui.js";
 /**
  * Read the current window/focus state, gated on the prompt-free capability
@@ -45,7 +45,8 @@ export async function readUiStateReport(deps = {}) {
             warnings: [],
         };
     }
-    if (!state.thingsRunning) {
+    const unproven = state.stalledProbes.length > 0 || state.failedProbes.length > 0;
+    if (!state.thingsRunning && !unproven) {
         return {
             available: true,
             detail: "Things is not running, so it has no window and no dialog open",
@@ -57,21 +58,45 @@ export async function readUiStateReport(deps = {}) {
     return {
         available: true,
         detail: describeUiState(state),
-        remediation: [],
+        // #629: a probe that did not answer is REPORTED, with what to do about it —
+        // never swallowed into a confident-looking summary, and never collapsed
+        // into a bare "nothing could be read". Everything the other probes DID
+        // prove is in `state` and in the summary above.
+        remediation: unproven
+            ? [
+                "one or more of the screen reads did not answer; check that Things is responding, then " +
+                    "run this again",
+            ]
+            : [],
         state,
         warnings: state.sheetOpen ? [SYNC_GATE_WARNING] : [],
     };
 }
+/** Render the per-probe verdicts, or "" when every probe answered. */
+function probeLine(state) {
+    const unprovenText = describeUnprovenProbes(state);
+    return unprovenText === "" ? [] : [`unproven:   ${unprovenText}`];
+}
 /** The human render, shared by `things ui-state` and `things doctor --ui-state`. */
 export function uiStateLines(report) {
     const lines = ["── Window state ──", `summary:     ${report.detail}`];
     const state = report.state;
     if (state !== null) {
-        lines.push(`frontmost:   ${state.frontmostApp ?? "unknown"}${state.thingsFrontmost ? " (Things)" : ""}`, `dialog:      ${state.sheetKind}${state.sheetKind === "none"
-            ? ""
-            : ` (${state.sheetForm}; ${state.sheetControls ?? "no census"})`}`, `focus:       ${state.focusOwner === null
-            ? "unknown"
-            : `${state.focusOwner.app} · ${state.focusOwner.role || "no focused element"}${state.focusOwner.subrole === null ? "" : ` / ${state.focusOwner.subrole}`}`}`, `inspectable: ${state.inspectable ? "yes" : "no — a system dialog macOS does not expose"}`);
+        // #629: a row whose probe did not answer says so. Printing the field's
+        // unset default ("none", "unknown") next to rows that WERE measured is what
+        // made a stalled inspection read as a clean screen.
+        const unproven = (p) => state.stalledProbes.includes(p) || state.failedProbes.includes(p);
+        lines.push(`frontmost:   ${unproven("frontmost")
+            ? "not established"
+            : `${state.frontmostApp ?? (unproven("frontapp") ? "not established" : "unknown")}${state.thingsFrontmost ? " (Things)" : ""}`}`, `dialog:      ${unproven("dialog")
+            ? "not established"
+            : `${state.sheetKind}${state.sheetKind === "none"
+                ? ""
+                : ` (${state.sheetForm}; ${state.sheetControls ?? "no census"})`}`}`, `focus:       ${unproven("focus")
+            ? "not established"
+            : state.focusOwner === null
+                ? "unknown"
+                : `${state.focusOwner.app} · ${state.focusOwner.role || "no focused element"}${state.focusOwner.subrole === null ? "" : ` / ${state.focusOwner.subrole}`}`}`, `inspectable: ${state.inspectable ? "yes" : "no — a system dialog macOS does not expose"}`, ...probeLine(state));
     }
     for (const warning of report.warnings)
         lines.push(`  warning:   ${warning}`);

package/dist/ui-state.js.map

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

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

@@ -65,6 +65,39 @@ export type UiSheetForm = "none" | "attached" | "detached";
  * `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";
+/**
+ * The census's individually-budgeted probes, in the order they run. The first
+ * three are DECISION-CRITICAL — the guard, the drive preflight and the cleanup
+ * ladder all decide on them — and the last two are DECORATION for the refusal
+ * copy. That order is the point: everything a caller acts on is proven before a
+ * single unaddressed query is attempted.
+ *
+ *   - `running`  — is there a Things process at all (a name-keyed lookup);
+ *   - `frontmost` — `frontmost of process "Things3"`, ADDRESSED: the one fact a
+ *                   keystroke guard actually needs;
+ *   - `dialog`   — the dialog shell, its form, its stack depth and its control
+ *                   census, all addressed inside `process "Things3"`;
+ *   - `frontapp` — WHICH other application owns the screen. This is the whole
+ *                   process table enumerated (`first application process whose
+ *                   frontmost is true`), so it runs only when the addressed
+ *                   `frontmost` probe already said the answer is not Things, and
+ *                   only for the sentence that names the thief;
+ *   - `focus`    — the focused element's role, through
+ *                   `AXFocusedUIElement`. MEASURED at ~3.5x the cost of every
+ *                   addressed probe in this vector even on a bare clone
+ *                   (docs/lab/fgrd2-census-hardening.md §2), and it decides
+ *                   nothing — so it goes last, inside its own budget, and its
+ *                   absence costs a clause in a sentence.
+ */
+export type UiProbe = "running" | "frontmost" | "dialog" | "frontapp" | "focus";
+/**
+ * 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 declare const CENSUS_TIMEOUT_MS = 12000;
 /** 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"). */
@@ -105,9 +138,30 @@ export interface UiState {
      * 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.
+     *
+     * A probe that TIMED OUT does not set this: "macOS refused to describe the
+     * screen" and "the screen did not answer in time" are different facts with
+     * different remediations, and #629 is what conflating them costs.
      */
     inspectable: boolean;
+    /**
+     * The probes that did not answer within their budget. Non-empty means the
+     * corresponding fields are UNPROVEN, not false — every caller reads them that
+     * way, and a critical probe here aborts a drive instead of being retried.
+     */
+    stalledProbes: UiProbe[];
+    /**
+     * The probes that answered with an error rather than a value (the surface is
+     * there but would not describe itself — a secure modal, a process that exited
+     * between two reads). Reported for the same reason: what could not be proven
+     * is named, never guessed at.
+     */
+    failedProbes: UiProbe[];
 }
+/** Did a probe the caller has to DECIDE on fail to answer? */
+export declare function censusUnverifiable(state: UiState | null): boolean;
+/** Name the probes that did not answer, for a diagnostic someone has to act on. */
+export declare function describeUnprovenProbes(state: UiState): string;
 /** 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). */
@@ -115,10 +169,34 @@ 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.
+ * 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 declare function axUiStateScript(): string;
 /**
@@ -131,8 +209,11 @@ 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).
+ *
+ * `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 declare function readUiState(run: (command: UiCommand, timeoutMs: number) => Promise<UiRunResult>, timeoutMs: number): Promise<UiState | null>;
+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
@@ -141,7 +222,14 @@ export declare function readUiState(run: (command: UiCommand, timeoutMs: number)
  * 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. */
+/**
+ * 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 declare function describeUiState(state: UiState): string;
 /**
  * The warning an OPEN Things dialog earns, wherever it is reported.