things-api 0.19.3 → 0.20.0

package/dist/write/verify/poller.js

@@ -25,7 +25,9 @@ export async function pollUntilVerified(evaluate, timeoutMs, deps = {}) {
                 observed: last.observed,
                 ...(last.discoveredUuid !== undefined && { discoveredUuid: last.discoveredUuid }),
                 ...(last.repeating !== undefined && { repeating: last.repeating }),
-                ...(last.repeatingWarnings !== undefined && { repeatingWarnings: last.repeatingWarnings }),
+                ...(last.repeatingDisclosures !== undefined && {
+                    repeatingDisclosures: last.repeatingDisclosures,
+                }),
             };
         }
         // UNEXPLAINED DELTA (CGRD1 guard 3): the requested change LANDED — the

package/dist/write/verify/poller.js.map

@@ -1 +1 @@
-{"version":3,"file":"poller.js","sourceRoot":"","sources":["../../../src/write/verify/poller.ts"],"names":[],"mappings":"AA2BA,6FAA6F;AAC7F,MAAM,yBAAyB,GAAG,CAAC,CAAC;AACpC,6FAA6F;AAC7F,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAuBpC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAA+B,EAC/B,SAAiB,EACjB,OAAmB,EAAE;IAErB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1F,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC;IACtB,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IACrC,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,IAAI,GAA2B,IAAI,CAAC;IACxC,iFAAiF;IACjF,oEAAoE;IACpE,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,IAAI,WAAW,GAAG,OAAO,CAAC;IAC1B,IAAI,WAAW,GAAG,CAAC,CAAC;IAEpB,SAAS,CAAC;QACR,QAAQ,IAAI,CAAC,CAAC;QACd,IAAI,GAAG,QAAQ,EAAE,CAAC;QAClB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO;gBACL,IAAI,EAAE,IAAI;gBACV,QAAQ;gBACR,SAAS,EAAE,GAAG,EAAE,GAAG,OAAO;gBAC1B,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,GAAG,CAAC,IAAI,CAAC,cAAc,KAAK,SAAS,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC;gBACjF,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;gBAClE,GAAG,CAAC,IAAI,CAAC,iBAAiB,KAAK,SAAS,IAAI,EAAE,iBAAiB,EAAE,IAAI,CAAC,iBAAiB,EAAE,CAAC;aAC3F,CAAC;QACJ,CAAC;QACD,uEAAuE;QACvE,8EAA8E;QAC9E,2EAA2E;QAC3E,0EAA0E;QAC1E,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChE,OAAO;gBACL,IAAI,EAAE,YAAY;gBAClB,QAAQ;gBACR,SAAS,EAAE,GAAG,EAAE,GAAG,OAAO;gBAC1B,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;aAC1D,CAAC;QACJ,CAAC;QACD,4EAA4E;QAC5E,yEAAyE;QACzE,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC3B,OAAO;gBACL,IAAI,EAAE,UAAU;gBAChB,QAAQ;gBACR,SAAS,EAAE,GAAG,EAAE,GAAG,OAAO;gBAC1B,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;aAC1D,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC;QAChC,IAAI,GAAG,EAAE,IAAI,QAAQ,EAAE,CAAC;YACtB,MAAM,IAAI,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC;YAC5F,OAAO;gBACL,IAAI;gBACJ,QAAQ;gBACR,SAAS,EAAE,OAAO;gBAClB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;aAC1D,CAAC;QACJ,CAAC;QACD,gFAAgF;QAChF,gFAAgF;QAChF,8EAA8E;QAC9E,gFAAgF;QAChF,IAAI,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YACpD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC1C,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtB,WAAW,IAAI,CAAC,CAAC;YACnB,CAAC;iBAAM,CAAC;gBACN,SAAS,GAAG,GAAG,CAAC;gBAChB,WAAW,GAAG,GAAG,EAAE,CAAC;gBACpB,WAAW,GAAG,CAAC,CAAC;YAClB,CAAC;YACD,IACE,WAAW,IAAI,yBAAyB;gBACxC,GAAG,EAAE,GAAG,WAAW,IAAI,sBAAsB,EAC7C,CAAC;gBACD,OAAO;oBACL,IAAI,EAAE,UAAU;oBAChB,QAAQ;oBACR,SAAS,EAAE,GAAG,EAAE,GAAG,OAAO;oBAC1B,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;iBAC1D,CAAC;YACJ,CAAC;QACH,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,IAAI,CAAC;YACjB,WAAW,GAAG,CAAC,CAAC;QAClB,CAAC;QACD,0HAA0H;QAC1H,MAAM,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC"}
+{"version":3,"file":"poller.js","sourceRoot":"","sources":["../../../src/write/verify/poller.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "things-api",
-  "version": "0.19.3",
+  "version": "0.20.0",
   "description": "Typed TypeScript library + CLI for Things 3 (Cultured Code) — verified writes, audit trail, schema-drift detection",
   "homepage": "https://github.com/mikegreiling/things-api#readme",
   "bugs": {

package/schema/envelope.schema.json

@@ -67,7 +67,6 @@
         "move-plan",
         "project-reopen",
         "doctor",
-        "ui-state",
         "capabilities",
         "config",
         "legend",
@@ -363,7 +362,7 @@
     },
     "ErrorCode": {
       "type": "string",
-      "description": "The registry of stable machine-readable error codes an error envelope can carry — the compiler IS the registry. Every `error.code` value the surfaces emit is a member of this union, and the human-readable meaning of each is frozen at v1.0 (new codes may still be ADDED after v1.0 — that is non-breaking; a documented code's MEANING never changes). The canonical per-code table (meaning + the `detail` keys each may carry) lives in `docs/contract.md` (The error-code registry).\n\nTwo members are template-literal families rather than fixed strings, because their suffix is minted in the write layer and the core deliberately never depends on it (see  {@link  blockedCode }  /  {@link  verifyFailedCode } ):  - `verify-failed:${reason}` — a single mutation executed but read-after-write    verification failed; the suffix is the reason (`timeout` | `mismatch` |    `silent-noop` | `ui-unreachable` | `collateral`). The bare `verify-failed`    (no suffix) is the multi-leg move/reorder failure.  - `blocked:${suffix}` — a mutation refused before touching the app; the    suffix is the specific hazard id (`H-…`) when one is named, else the block    reason (`drift` | `disruption-tier` | `lock` | `environment` | `clock` |    `scope`). The bare `blocked` is a policy refusal from the move planner.\n\n`blocked:drift` maps to exit code 5 (DriftBlocked); every other `blocked:*` maps to exit code 4 (Blocked)."
+      "description": "The registry of stable machine-readable error codes an error envelope can carry — the compiler IS the registry. Every `error.code` value the surfaces emit is a member of this union, and the human-readable meaning of each is frozen at v1.0 (new codes may still be ADDED after v1.0 — that is non-breaking; a documented code's MEANING never changes). The canonical per-code table (meaning + the `detail` keys each may carry) lives in `docs/contract.md` (The error-code registry).\n\nTwo members are template-literal families rather than fixed strings, because their suffix is minted in the write layer and the core deliberately never depends on it (see  {@link  blockedCode }  /  {@link  verifyFailedCode } ):  - `verify-failed:${reason}` — a single mutation executed but read-after-write    verification failed; the suffix is the reason (`timeout` | `mismatch` |    `silent-noop` | `ui-unreachable` | `collateral`). The bare `verify-failed`    (no suffix) is the multi-leg move/reorder failure.  - `blocked:${suffix}` — a mutation refused before touching the app; the    suffix is the specific hazard id (`H-…`) when one is named, else the block    reason (`drift` | `disruption-tier` | `lock` | `environment` | `clock` |    `scope` | `reconcile` | `in-flight`). The bare `blocked` is a policy    refusal from the move planner.\n\n`blocked:drift` maps to exit code 5 (DriftBlocked); every other `blocked:*` maps to exit code 4 (Blocked)."
     }
   },
   "title": "things-api envelope",

package/skills/things-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: things-cli
 description: Read and manage a user's tasks in the Things 3 app (macOS) through the `things` CLI — list views like Today/Inbox/Upcoming, search, and create, edit, schedule, complete, move, or organize to-dos, projects, areas, headings, and tags. Use whenever the user asks about their tasks, to-dos, projects, or anything in Things.
-version: 0.19.3
+version: 0.20.0
 ---
 
 # Things CLI
@@ -67,7 +67,9 @@ Namespaced verb families — run `things <group> --help` for the verbs and `thin
 
 **Guarded writes** surface their consequence and require an explicit flag: deleting a NON-EMPTY area needs `--allow-non-empty`, a permanent delete needs `--dangerously-permanent`, and a UI-driving op (e.g. `area reorder`, `make-repeating`) needs `--dangerously-drive-gui` plus `things config set ui-enabled true`. The full acknowledgment contract is in [references/errors.md](references/errors.md).
 
-**UI-driving ops are slow — allow a generous timeout, and NEVER read a timeout as success.** A `--dangerously-drive-gui` op visibly drives the Things app and can take OVER A MINUTE on a large, syncing database. Give the command a longer-than-normal wrapper timeout — **at least 180s** when your harness allows it (120s is the floor), and pass `--verify-timeout 120000` or more so the app's own budget outlasts the drive. The cardinal rule: **a timeout, EMPTY output, or a silent no-op is NOT a success** — treat it as "outcome unknown". If your own timeout kills the command first you get EMPTY output (not a result, not an error) and the change MAY STILL have landed; if the app's budget is exceeded first you get a structured timeout that says the outcome is uncertain. In BOTH cases, before doing anything else **re-read the item with `things show <uuid>`** (and, on a dev checkout, check the trace under `~/.local/state/things-api/trace/`) to learn what actually happened. **If your harness KILLS long commands** at a cap you cannot raise, pass `--op-id <key>` on the write, let it die, then run **`things op-result <key>`** in a fresh command — it reads the change history the killed process already wrote and reports whether the op landed (`found`), is still-running/died-mid-flight (`intent-only`, outcome UNCERTAIN), or never recorded (`unknown`). **Do NOT fire an identical retry** — repeated blind retries after a timeout or a kill are exactly how you get duplicate or half-configured series (the original item trashed, a wrong template created). If the state is wrong or ambiguous and a re-read does not clarify it, **STOP and file a bug** with the trace rather than retrying. A genuine success always returns a structured JSON result (with `--json`) naming the new/updated uuid; anything else is not a success. **If a drive reports that a dialog may still be open in Things, run `things ui-state --json` before anything else** — it reports, without touching anything, whether a dialog is open, which one, and which application currently owns the keyboard. An open dialog is not cosmetic: while one stands, Things ignores this kind of change and stops sending anything to Things Cloud, so the next command will fail the same way until it is dismissed. The trace can hold real task titles, so never paste it into a public issue.
+**Put `--op-id <key>` on every write you might retry.** It costs nothing and it is the only thing that makes a retry safe: a resubmission under the same key replays the first result instead of repeating the change, and if the first is *still running* the second is refused rather than executed. Without a key, a retry after a timeout is a second execution.
+
+**UI-driving ops are slow — allow a generous timeout, and NEVER read a timeout as success.** A `--dangerously-drive-gui` op visibly drives the Things app and takes SECONDS, over a minute on a large, syncing database. Order your two budgets so the app's outlasts yours in neither direction by accident: pass `--verify-timeout 120000` or more, and set your wrapper/tool timeout ABOVE it — **at least 180s** when your harness allows it (120s is the floor). The cardinal rule: **a timeout, EMPTY output, or a silent no-op is NOT a success** — treat it as "outcome unknown". If your own timeout kills the command first you get EMPTY output (not a result, not an error) and the change MAY STILL have landed; if the app's budget is exceeded first you get a structured timeout that says the outcome is uncertain. **In both cases, do not read the item and guess — run `things op-result <key>`.** It reads the change history the killed process already wrote and answers with one of: `found` (the real result), `in-flight` (still running — call it again in a few seconds; do NOT re-send the write), `orphaned` (it started and its process ended without recording an outcome — outcome UNCERTAIN), or `unknown` (never recorded). Only when you have no key does re-reading with `things show <uuid>` become the fallback. **Do NOT fire an identical retry** — repeated blind retries after a timeout or a kill are exactly how you get duplicate or half-configured series (the original item trashed, a wrong template created). If the state is wrong or ambiguous and `op-result` does not clarify it, **STOP and file a bug** with the trace (`~/.local/state/things-api/trace/`, on a dev checkout) rather than retrying. A genuine success always returns a structured JSON result (with `--json`) naming the new/updated uuid; anything else is not a success. **If a drive reports that a dialog may still be open in Things, run `things rescue status --json` before anything else** — it reports, without touching anything, whether a dialog is open, which one, which application currently owns the keyboard, and whether another command is holding the change lock. An open dialog is not cosmetic: while one stands, Things ignores this kind of change and stops sending anything to Things Cloud, so the next command will fail the same way until it is dismissed. The trace can hold real task titles, so never paste it into a public issue.
 
 **Quick skeletons**: `things todo add "T1" "T2" "T3" [shared flags]` creates several to-dos in one call (every shared flag — `--project`/`--area`/`--when`/`--tags`/… — applies to each; `--id-only` prints the new uuids one per line for chaining; one `undoToken` removes the set). To stand up a new project with children, `things project add "<title>" --todo "T1" --todo "T2" …` (repeatable). For richer per-item metadata or cross-item references, use `things batch`.
 

package/skills/things-cli/references/repeating.md

@@ -69,7 +69,7 @@ These commands visibly drive the Things app and are slow — often OVER A MINUTE
 
 - Allow a generous wrapper timeout — **at least 180s** where your harness permits (120s floor) — and pass `--verify-timeout 120000` or more so the app's own budget outlasts the drive.
 - **A timeout, empty output, or a silent no-op is NOT success** — treat it as "outcome unknown". Before doing anything else, re-read the item with `things show <ref>` (and, on a dev checkout, the trace under `~/.local/state/things-api/trace/`) to learn what actually landed.
-- **If your environment kills long commands** (a hard wall-time cap you cannot raise): pass `--op-id <key>` on the write, let the command die, then run **`things op-result <key>`** in a fresh command to read what actually happened — it reads the local change history the killed process already wrote and reports `found` (the final result + target), `intent-only` (started but no outcome recorded — still running or the process died mid-flight, outcome UNCERTAIN), or `unknown`. This is the recovery path for a capped harness; do NOT infer the outcome from the kill. (`--op-id` works on the single-op repeat verbs like `reschedule-repeat`; `make-repeating` / `add-repeating` are compounds — express them as a `batch` line with a per-line `opId` if you need this.)
+- **Pass `--op-id <key>` on any of these you might retry**, and if the command dies (a hard wall-time cap you cannot raise), run **`things op-result <key>`** in a fresh command rather than inferring the outcome from the kill. It reads the local change history the killed process already wrote and reports `found` (the final result + target), `in-flight` (still running — call it again in a few seconds, do NOT re-send the write), `orphaned` (started, then its process ended without recording an outcome — UNCERTAIN), or `unknown`. The key also makes the retry itself safe: a resubmission replays the first result, and one sent while the first is still running is refused rather than executed. Every repeat verb takes it, `make-repeating` / `add-repeating` included — those are multi-leg but record ONE result, so the key addresses the whole verb.
 - **Never fire an identical retry** after a timeout or a kill — a blind retry is how you get a duplicate or half-configured series (original trashed, wrong template created). Learn the real outcome first (`things op-result` / `things show`); if the state is wrong or ambiguous, STOP and file a bug with the trace.
 - These ops need Things reachable on the current desktop (not a locked screen or a covering full-screen app); a session it cannot reach is refused cleanly with a remediation, touching nothing.
 - A genuine success always returns a structured JSON result (with `--json`) naming the new/updated uuid.

package/dist/cli/commands/ui-state.d.ts

@@ -1,11 +0,0 @@
-/**
- * `things ui-state` — a read-only look at what is on the screen: whether a
- * dialog is open in Things, which dialog it is, whether Things is frontmost,
- * and which application owns the keyboard. Thin surface over the library's
- * readUiStateReport().
- *
- * Nothing is clicked, typed, activated or dismissed. Always exit 0: an
- * unreadable screen is a reported state, not a command failure.
- */
-import type { Command } from "commander";
-export declare function registerUiState(program: Command): void;

package/dist/cli/commands/ui-state.js

@@ -1,27 +0,0 @@
-import { okEnvelope, readUiStateReport, uiStateLines } from "../../index.js";
-export function registerUiState(program) {
-    program
-        .command("ui-state")
-        .description("Report what is on the screen right now: whether a dialog is open in Things and which one, " +
-        "whether Things is the frontmost app, and which application owns the keyboard. Reads " +
-        "only — nothing is clicked, typed or dismissed. Says so plainly when a system dialog is " +
-        "covering the screen, since macOS does not let any app inspect one. Always exit 0.")
-        .option("--json", "emit versioned JSON envelope on stdout")
-        .action(async (opts) => {
-        const started = Date.now();
-        const report = await readUiStateReport();
-        const meta = {
-            dbVersion: null,
-            fingerprint: "unknown",
-            elapsedMs: Date.now() - started,
-        };
-        if (opts.json) {
-            process.stdout.write(`${JSON.stringify(okEnvelope("ui-state", report, meta))}\n`);
-        }
-        else {
-            process.stdout.write(`${uiStateLines(report).join("\n")}\n`);
-        }
-        process.exitCode = 0;
-    });
-}
-//# sourceMappingURL=ui-state.js.map

package/dist/cli/commands/ui-state.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ui-state.js","sourceRoot":"","sources":["../../../src/cli/commands/ui-state.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,YAAY,EAAqB,MAAM,gBAAgB,CAAC;AAEhG,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO;SACJ,OAAO,CAAC,UAAU,CAAC;SACnB,WAAW,CACV,4FAA4F;QAC1F,sFAAsF;QACtF,yFAAyF;QACzF,mFAAmF,CACtF;SACA,MAAM,CAAC,QAAQ,EAAE,wCAAwC,CAAC;SAC1D,MAAM,CAAC,KAAK,EAAE,IAAwB,EAAE,EAAE;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,MAAM,iBAAiB,EAAE,CAAC;QACzC,MAAM,IAAI,GAAiB;YACzB,SAAS,EAAE,IAAI;YACf,WAAW,EAAE,SAAS;YACtB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;SAChC,CAAC;QACF,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QACpF,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACP,CAAC"}