things-api 0.9.0 → 0.11.0

package/README.md

@@ -2,7 +2,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.7.0 — 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 two lab-validated write vectors (URL scheme + AppleScript) 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 ordering across eight scopes (incl. a project's headings and the top-level sidebar projects). A third surface — Apple Shortcuts — is now wired for the two headless capabilities nothing else can do: creating a heading in an existing project (`things heading add`) and clearing a reminder from a date-scheduled item (`things todo clear-reminder`). Both run through bundled proxy shortcuts (`things setup shortcuts`) and are gated on their presence. 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.11.0 — 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 ordering across eight scopes (incl. a project's headings and the top-level sidebar projects). The Apple Shortcuts surface is wired for the two headless capabilities nothing else can do: creating a heading in an existing project (`things heading add`) and clearing a reminder from a date-scheduled item (`things todo clear-reminder`). Both run through bundled proxy shortcuts (`things setup shortcuts`) 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
@@ -15,7 +15,7 @@ things capabilities --op todo.delete   # what's possible, per vector, with evide
 
 ## Requirements & first-run setup
 
-Things 3 installed and launched once, Node ≥ 24, and a handful of one-time macOS consents / Things settings depending on what you use (file-access consent for reads; "Enable Things URLs" + Automation consents for writes). **See [docs/setup.md](docs/setup.md)** — including the dedicated-automation-Mac checklist. `things doctor` validates your setup and prints remediation for anything missing.
+Things 3 installed and launched once, Node ≥ 24, and a handful of one-time macOS consents / Things settings depending on what you use (file-access consent for reads; "Enable Things URLs" + Automation consents for writes; an Accessibility grant for the optional GUI vector). **See [docs/setup.md](docs/setup.md)** — including the dedicated-automation-Mac checklist. `things doctor` validates your setup and prints remediation for anything missing.
 
 ### Shortcuts setup (optional)
 
@@ -27,7 +27,15 @@ things setup shortcuts   # opens an install sheet per missing shortcut — click
 
 On each shortcut's first run macOS asks for permission — choose **Always Allow** so later runs are unattended (the two delete shortcuts re-ask on every run by design; Apple offers no always-allow for deletion). `things setup shortcuts --check` and `things doctor` report installation state.
 
-Once installed, these Shortcuts-only operations become available as ordinary commands: `things heading add <project> <title>` (create a heading in an existing project) and `things todo clear-reminder <uuid>` (clear a date-scheduled to-do's reminder while keeping its date). Both are also exposed over MCP (`create_heading`, `clear_reminder`). If a required shortcut is missing, the command is blocked up front with a pointer back to `things setup shortcuts` — nothing is dispatched.
+Once installed, these Shortcuts-only operations become available as ordinary commands: `things heading add <project> <title>` (create a heading in an existing project) and `things todo clear-reminder <uuid>` (clear a date-scheduled to-do's reminder while keeping its date). Both are also exposed over MCP (the `heading` tool's create action, and `clear_reminder`). If a required shortcut is missing, the command is blocked up front with a pointer back to `things setup shortcuts` — nothing is dispatched.
+
+### Accessibility GUI vector (optional, off by default)
+
+A handful of transforms exist on **no scriptable surface at all** — the URL scheme, AppleScript, and Shortcuts cannot express them. The fourth write vector (the "ui" vector) reaches them by driving the local Things app's real interface through macOS Accessibility. It unlocks: making an existing to-do or project repeat and rescheduling/pausing/resuming its rule; converting a to-do into a project; and moving an area to a new position in the global area order (the sidebar). See [docs/design/ui-vector.md](docs/design/ui-vector.md) for the full model.
+
+Because it drives the live GUI it is **fail-closed and two-key gated**: enable it once with `things config set ui-enabled true`, then acknowledge each individual call with `--dangerously-drive-gui` (`dangerously_drive_gui` over MCP). It carries the `H-UI-DRIVE` hazard, sits at the top disruption tier (3), and is intended for a dedicated, always-on Mac pinned to the English app language (a non-English UI fails the vector closed). Its recipes are **fragile** — an app-layout change can break them — so each op carries a per-op certification status (`uncertified` → `lab-certified` → on-device `certified`) recorded in the manifest at [src/write/vectors/ui-certification.ts](src/write/vectors/ui-certification.ts) and surfaced by `things capabilities` and the `things doctor` ui-vector section; a successful drive of a not-yet-`certified` op returns a note saying so.
+
+Setup — granting Accessibility to the driving process and verifying it with `things doctor --probe-accessibility` — is in [docs/setup.md](docs/setup.md).
 
 ### Development install
 
@@ -42,23 +50,24 @@ Edits under `src/` take effect immediately. The bin launcher ([bin/things.js](bi
 
 ## Core principles
 
-- **Reads** go directly to Things' local SQLite database (read-only, WAL-aware). **Writes** go exclusively through official app surfaces — URL scheme, AppleScript, Shortcuts — never direct DB writes (sync corruption).
+- **Reads** go directly to Things' local SQLite database (read-only, WAL-aware). **Writes** go exclusively through official app surfaces — URL scheme, AppleScript, Shortcuts, and (opt-in) the Accessibility-driven GUI — never direct DB writes (sync corruption).
 - **Every mutation is verified**: pre-read → hazard guards → execute → poll re-read until the expected delta appears. Silent no-ops are failures.
 - **Every mutation is audited**: JSONL trail (`~/.local/state/things-api/audit/`) with requested vs. observed deltas; auth tokens structurally redacted.
-- **Schema drift is detected**: table/column fingerprints keyed by Things' database version; writes hard-block on mismatch ([drift runbook](docs/lab/drift-runbook.md)).
-- **Disruption is explicit**: every operation×vector combination carries a disruption tier (0 = invisible → 3 = navigates UI/modals); disruptive operations require explicit opt-in flags.
+- **Schema drift is detected**: table/column fingerprints keyed by Things' database version; writes hard-block on mismatch, and reads surface a non-blocking `meta.warnings` note rather than failing ([drift runbook](docs/lab/drift-runbook.md)).
+- **Disruption is explicit**: every operation×vector combination carries a disruption tier (0 = invisible → 3 = drives the live UI); disruptive operations require explicit opt-in flags.
 - **Nothing is developed against production data**: probing and integration tests run in disposable Tart macOS VMs.
 
 ## For agents
 
 The CLI is designed to be driven by coding agents with no out-of-band knowledge. The contract:
 
-1. **Discovery**: `things --help` (ends with AGENT NOTES), per-command `--help` (states each write's vector, disruption tier, hazards, and exact acknowledgement flag names — regression-tested as API), and `things capabilities [--op <op>] --json` (the lab-validated operation × vector support matrix, with probe-evidence ids). Command invocation follows one grammar (`things <view>` · `things <type> <verb> <subject>` · loose `things <verb> <subject>` · bare `things <subject>`) with a single precedence chain — registered command/alias → view keyword → reference resolution — specified in [docs/design/cli-grammar.md](docs/design/cli-grammar.md).
-2. **Structured output**: every command takes `--json` → versioned envelope `{ apiVersion, ok, kind, data|error, meta }` on stdout; human chatter goes to stderr only. List views are **bounded by default**: the flat/chronological views (`inbox`, `today`, `upcoming`, `logbook`, `trash`, `search`, `changes`) return at most 50 items — raise with `--limit <n>` or lift with `--all` — and carry exact truncation counts in `meta.pagination { shown, total, limit, truncated }`. The grouped catalogues (`anytime`, `someday`) always show every area and project row and cap per block instead (no `--limit`): `--area-limit <n>` (default 30) per area block on both, `--project-limit <n>` (default 3) per project block on anytime, `--show-active-project-items [n]` for someday's trailing active-projects section — reporting `meta.grouped { truncated, blocks[] }` with per-block counts. Same defaults and metadata apply over MCP.
-3. **Stable exit codes**: `0` ok · `2` usage · `3` verify-failed (mutation executed, expected delta never appeared) · `4` blocked (hazard guard or disruption policy; error carries `remediation`) · `5` drift-blocked · `6` unsupported · `7` environment.
+1. **Discovery**: `things --help` (a grouped one-line-per-command index; orientation detail lives behind `things help <topic>` — `agent`, `filters`, `ids`, `output`, `writes`), per-command `things <command> --help` (behavior, side effects, and the exact acknowledgement flag names a write needs — regression-tested as API; by design it does **not** carry vector/tier/hazard vocabulary, which is banned from help text by [docs/design/surface-copy.md](docs/design/surface-copy.md) — that classification lives in `capabilities`), and `things capabilities [--op <op>] --json` (the lab-validated operation × vector support matrix with disruption tiers, hazards, per-op certification status, and probe-evidence ids). Command invocation follows one grammar (`things <view>` · `things <type> <verb> <subject>` · loose `things <verb> <subject>` · bare `things <subject>`) with a single precedence chain — registered command/alias → view keyword → reference resolution — specified in [docs/design/cli-grammar.md](docs/design/cli-grammar.md).
+2. **Structured output**: every command takes `--json` → versioned envelope `{ apiVersion, ok, kind, data|error, meta }` on stdout; human chatter goes to stderr only. List views are **bounded by default**: the flat/chronological views (`inbox`, `today`, `upcoming`, `logbook`, `trash`, `search`, `changes`) return at most 50 items — raise with `--limit <n>` or lift with `--all` — and carry exact truncation counts in `meta.truncation { shown, total, limit, truncated }` (the split `today` view also breaks the counts down per render section under `sections`). The grouped catalogues (`anytime`, `someday`) always show every area and project row and cap per block instead (no `--limit`): `--area-limit <n>` (default 30) per area block on both, `--project-limit <n>` (default 3) per project block on anytime, `--show-active-project-items [n]` for someday's trailing active-projects section — reporting `meta.grouped { truncated, blocks[] }`, where each block is identity-carrying (`kind`, `ref`, `title`, `shown`, `total`) and project blocks nest inside their area block under `children`. A read whose database schema no longer matches this build's validated fingerprint carries a non-blocking `meta.warnings` note (the read still returns best-effort; the same drift hard-blocks writes). Same defaults and metadata apply over MCP.
+3. **Stable exit codes**: `0` ok · `2` usage · `3` verify-failed (mutation executed, expected delta never appeared) · `4` blocked (hazard guard or disruption policy; error carries `remediation`) · `5` drift-blocked · `6` unsupported (op has no supported vector — `things batch` also aggregates to 6 when its only failures are unsupported ops) · `7` environment.
 4. **Plan before executing**: every write supports `--dry-run` — compiled invocation (token-redacted), chosen vector, tier, hazards checked, expected delta. Nothing runs, nothing is audited.
-5. **No prompts, ever**: risky semantics are explicit flags — `--children require-resolved|auto-complete` (project completion cascades), `--acknowledge-checklist-reset` (checklist replacement destroys per-item state), `--acknowledge-project-reopen` (open child reopens a resolved project), `--dangerously-permanent` (area/tag delete and empty-trash skip the Trash).
-6. **Experimental surfaces are opt-in**: `things reorder` (ordering within Today, the Inbox, Someday, a project's to-dos, a project's headings, or an area) rides an undocumented AppleScript command that any Things update may remove. It requires `things config set allow-experimental true` and re-checks the app's sdef declaration before every dispatch; `things doctor` reports both gates. Two scopes never touch it: This Evening and the top-level sidebar projects use verified `when=` round-trips (the "bounce", ≤10 items) instead.
+5. **No prompts, ever**: risky semantics are explicit flags — `--children require-resolved|auto-complete` (project completion cascades), `--acknowledge-checklist-reset` (checklist replacement destroys per-item state), `--acknowledge-project-reopen` (open child reopens a resolved project), `--dangerously-permanent` (area/tag delete and empty-trash skip the Trash), `--dangerously-drive-gui` (each Accessibility GUI-vector call).
+6. **Experimental surfaces are opt-in**: `things reorder` (ordering within Today, the Inbox, Someday, a project's to-dos, a project's headings, or an area) rides an undocumented AppleScript command that any Things update may remove. It requires `things config set allow-experimental true` and re-checks the app's sdef declaration before every dispatch; `things doctor` reports both gates. Two scopes never touch it: This Evening and the top-level sidebar projects use verified `when=` round-trips (the "bounce", ≤10 items) instead. Reordering the areas themselves (the sidebar order) is a separate operation on the Accessibility GUI vector (`things area reorder`, MCP `reorder` with `scope=areas`).
+7. **Consumer timezone (optional)**: date boundaries (today / evening / upcoming / logbook sweep / overdue / since-until) evaluate in the host's zone by default. Set `THINGS_TZ` (an IANA zone) so they render for another calendar — e.g. an always-on Mac queried three zones away; over MCP the date-sensitive read tools and the `when`-bearing write tools also take a per-call `tz` that overrides it. `THINGS_NOW` (an ISO instant) pins "now" for determinism. When either is in effect a response carries `meta.clock { timezone, today }` (absent on the host clock); invalid values fail closed (exit 2). Writing `when` = today resolves to that zone's date before dispatch; `when` = evening is refused when the consumer's day differs from the app machine's (This Evening exists only for the app machine's current day). Reminder times are wall-clock and never shifted. For a dedicated single-consumer host, aligning the system timezone (`sudo systemsetup -settimezone <zone>`) is the simpler path — see [docs/design/contracts.md](docs/design/contracts.md#deployment-note--host-timezone-alignment).
 
 A typical mutation flow:
 
@@ -75,6 +84,28 @@ things undo                                    # execute it — verified like an
 
 Failure modes are first-class: a `verify-failed:silent-noop` means the app accepted the command and did nothing (a real Things behavior the guards mostly prevent — see [docs/things-app-oddities.md](docs/things-app-oddities.md)); `blocked:*` responses include machine-readable remediation.
 
+## Agent skill
+
+An [agent skill](skills/things-cli/SKILL.md) ships in the package: a compact orientation an agent loads once — the data model, how to refer to items, and the stable machine contracts — pointing at `things --help` and `things help <topic>` for the fast-moving mechanics. **Install the skill and the rest self-maintains:** CLI access is via whatever `things` (or `npx`) resolves, mechanics come from that binary's own help, and version nudges flow both ways.
+
+Install (or update) it with one command:
+
+```sh
+things install-skill          # global: covers every agent harness the skills CLI detects
+things install-skill --project   # into the current project's .agents instead
+things install-skill --check     # compare installed vs bundled version, write nothing
+```
+
+Under the hood it hands the bundled skill to the [`skills` CLI](https://github.com/vercel-labs/skills) (`npx -y skills add …`), which keeps one canonical copy under `~/.agents/skills/` and materializes it into each detected agent's directory (`~/.claude/skills/`, `~/.codex/skills/`, …). When that tool or the network is unavailable it falls back to a plain copy into `~/.agents` and `~/.claude`. **Re-running `things install-skill` IS the update** — it replaces the skill wholesale — so prefer it over a generic `skills update` for this skill (a single, unambiguous update path).
+
+Three entry angles, all converging on the same working setup:
+
+- **CLI installed** (`npm i -g things-api`) → `things --help` suggests `things install-skill`.
+- **No install** → `npx things-api install-skill` places the skill; the skill itself falls back to `npx -y things-api@latest` for every command, so it works with no global binary on PATH.
+- **Skill first, zero npm knowledge** → `npx skills add mikegreiling/things-api` pulls the skill straight from GitHub (whatever `skills/things-cli/` currently holds).
+
+To keep the two sides from drifting, the `things` binary carries a version-stamped copy of the skill and (on human/`--help` output only, never `--json`) notes when the installed skill is well behind it. That notice reads the well-known skill directories under `~/.agents` and `~/.claude`; disable it with `THINGS_API_NO_SKILL_CHECK=1`.
+
 ## Architecture: one library, thin surfaces
 
 The TypeScript library (`import { openThings } from "things-api"`) is the product; the CLI and the MCP server are thin presentation layers over the same `ThingsClient` — every read view and every verified mutation is a client method first. Shared machine contracts (JSON envelope, exit codes) live in the core (`contracts.ts`), and `diagnose()` / `capabilitiesTable()` are library functions the surfaces merely render.
@@ -87,4 +118,18 @@ The TypeScript library (`import { openThings } from "things-api"`) is the produc
 { "mcpServers": { "things": { "command": "things", "args": ["mcp"] } } }
 ```
 
-The server instructions carry the user's live inventory (areas, tag hierarchy, open projects — read at server start) plus the reference/scheduling vocabulary, so models can name real destinations without a discovery round-trip. Tools mirror the client surface: reads (`read_view` — today/inbox/anytime/upcoming with occurrence horizon/someday/logbook/trash — `search`, `changes_since`, `get_item`, `get_project`, `list_collections`) and grouped semantic mutations (`add_todo`, `update_todo`, `set_todo_status`, `move_todo`, `set_tags`, `edit_checklist`; `delete_item`/`restore_item`/`duplicate_item` for to-dos and projects alike; `add_project`, `update_project`, `set_project_status`, `move_project`; area and tag CRUD incl. tag un-nesting and guarded subtree deletion; plus generic `run_operation` for the full 28-op catalog, `batch`, `reorder`, `undo`, `capabilities`, `doctor`). Every write tool takes `dry_run`; tools carry read-only/destructive annotations; hazard blocks come back as structured tool errors carrying the same remediation text the CLI prints. Tool descriptions follow the consumer-voice contract in [docs/design/surface-copy.md](docs/design/surface-copy.md).
+The server instructions carry the user's live inventory (areas, tag hierarchy, open projects — read at server start) plus the reference/scheduling vocabulary, so models can name real destinations without a discovery round-trip. Tools mirror the client surface, grouped by area:
+
+The catalog is consolidated around a few verb-parameterized tools (a discriminator — `kind`, `scope`, or `action` — selects the variant, with per-variant requirements validated at call time). This keeps every capability reachable while shrinking the static tool surface a model must load.
+
+- **Reads**: `read_view` (today / inbox / anytime / upcoming with occurrence horizon / someday / logbook / trash), `search`, `changes_since`, `get_item`, `get_project`, `get_area`, `list_collections`.
+- **Editing**: `update` (`kind` todo / project / area / tag), `set_status` (`scope` todo / project — completed / canceled / open, with the project children policy), `delete` (`kind` item / area / tag — Trash for items, guarded permanent delete for areas/tags incl. tag subtrees).
+- **To-do writes**: `add_todo`, `move_todo`, `set_tags`, `edit_checklist`, plus completion/creation backdating (`backdate_todo`) and Logbook import (`add_logged_todo`).
+- **Project writes**: `add_project`, `move_project`.
+- **To-dos and projects alike**: `restore_item`, `duplicate_item`.
+- **Create**: `add_area`, `add_tag`.
+- **Headings & reminders** (Shortcuts-backed where headless-impossible): `heading` (`action` create / rename / archive / unarchive / convert_to_project), `clear_reminder`.
+- **Recurrence via the Accessibility GUI ("ui") vector** (two-key gated — `ui-enabled` config + `dangerously_drive_gui` per call): `repeat` (`scope` todo / project; `action` start / reschedule / pause / resume / create). The `heading` convert_to_project action and the `reorder` areas scope ride the same gated GUI surface.
+- **Generic & discovery**: `run_operation` (the full 49-op catalog), `batch`, `reorder` (item ordering across scopes, plus `scope=areas` for the sidebar area order), `undo`, `capabilities`, `doctor`.
+
+Every write tool takes `dry_run`; the GUI-driven variants additionally require `dangerously_drive_gui`; tools carry read-only/destructive annotations; hazard blocks come back as structured tool errors carrying the same remediation text the CLI prints. Tool descriptions follow the consumer-voice contract in [docs/design/surface-copy.md](docs/design/surface-copy.md).

package/dist/audit/log.js

@@ -2,9 +2,63 @@
  * JSONL audit writer: monthly files, never auto-deleted, structural token
  * redaction — the serializer refuses to emit any string containing the
  * loaded auth token.
+ *
+ * DURABILITY + TEAR-RESISTANCE (M5). Audit appends happen from processes that
+ * do NOT hold the mutation lock (e.g. a drift-gate or lock-contention block is
+ * recorded before/without ever acquiring it), so two things-api invocations can
+ * append to the same monthly file concurrently. The append path is therefore:
+ *
+ *   open(path, O_APPEND) → ONE writeSync(fd, completeLineBuffer) → fsyncSync → close
+ *
+ * Two properties make this safe for our use in practice, on regular files:
+ *  - ATOMIC APPEND. With O_APPEND the kernel positions the write at end-of-file
+ *    and performs the append under the inode lock, so a SINGLE write() call
+ *    cannot interleave with a concurrent write() from another fd — no torn or
+ *    spliced line. We hand writeSync the COMPLETE `${line}\n` buffer so exactly
+ *    one write() syscall carries the whole record. (The old appendFileSync path
+ *    gave neither a single-write guarantee nor a flush.)
+ *  - DURABILITY. fsyncSync flushes the record to disk before we return, so a
+ *    crash immediately after the append cannot lose an already-acknowledged
+ *    record — the pairing invariant the M3 intent record relies on holds.
+ *
+ * No lockfile is used, deliberately: for regular local files a single
+ * O_APPEND write() is already interleave-safe, our records are small and writes
+ * infrequent, and a lockfile would add a failure mode (stale locks, contention)
+ * into a path that must NEVER throw into the mutation result. A short write from
+ * write() only occurs on signals/full disks/pipes — not local regular-file
+ * appends of records this size — so the "one writeSync = one record" assumption
+ * holds; the >1MB round-trip test exercises the large-buffer case.
+ *
+ * NEVER THROWS INTO THE MUTATION PATH. If the durable path fails for any reason
+ * (fsync unsupported on an exotic FS, transient open error, …) we fall back to a
+ * best-effort plain append, and if THAT throws we swallow it: a mutation's
+ * result must never break because auditing hit an I/O error.
  */
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, closeSync, fsyncSync, mkdirSync, openSync, writeSync } from "node:fs";
 import { join } from "node:path";
+/** Durable single-write append (O_APPEND + fsync), best-effort fallback on failure. */
+function durableAppend(path, buf) {
+    try {
+        const fd = openSync(path, "a"); // "a" → O_APPEND
+        try {
+            writeSync(fd, buf); // one write() with the complete line — atomic append
+            fsyncSync(fd); // flush to disk before returning
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        // Best-effort fallback: try a plain append, then give up silently. An audit
+        // write must never throw into the mutation path that called it.
+        try {
+            appendFileSync(path, buf);
+        }
+        catch {
+            /* swallow — a mutation result must never break because auditing failed */
+        }
+    }
+}
 export function createAuditWriter(options) {
     const secrets = options.secrets.filter((s) => s.length > 0);
     return {
@@ -24,7 +78,7 @@ export function createAuditWriter(options) {
                 }
                 return value;
             });
-            appendFileSync(join(options.dir, `${month}.jsonl`), `${line}\n`);
+            durableAppend(join(options.dir, `${month}.jsonl`), Buffer.from(`${line}\n`, "utf8"));
         },
     };
 }

package/dist/audit/log.js.map

@@ -1 +1 @@
-{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/audit/log.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQjC,MAAM,UAAU,iBAAiB,CAAC,OAKjC;IACC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC5D,OAAO;QACL,MAAM,CAAC,MAAmB;YACxB,IAAI,CAAC,OAAO,CAAC,OAAO;gBAAE,OAAO;YAC7B,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU;YAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;gBAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC9B,IAAI,GAAG,GAAG,KAAK,CAAC;oBAChB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;wBAC7B,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC;4BAAE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;oBACrE,CAAC;oBACD,OAAO,GAAG,CAAC;gBACb,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC,CAAC,CAAC;YACH,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,KAAK,QAAQ,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC;QACnE,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/audit/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC/F,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQjC,uFAAuF;AACvF,SAAS,aAAa,CAAC,IAAY,EAAE,GAAW;IAC9C,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,iBAAiB;QACjD,IAAI,CAAC;YACH,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,qDAAqD;YACzE,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,iCAAiC;QAClD,CAAC;gBAAS,CAAC;YACT,SAAS,CAAC,EAAE,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;QAC5E,gEAAgE;QAChE,IAAI,CAAC;YACH,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;QAC5E,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAKjC;IACC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC5D,OAAO;QACL,MAAM,CAAC,MAAmB;YACxB,IAAI,CAAC,OAAO,CAAC,OAAO;gBAAE,OAAO;YAC7B,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU;YAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;gBAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC9B,IAAI,GAAG,GAAG,KAAK,CAAC;oBAChB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;wBAC7B,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC;4BAAE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;oBACrE,CAAC;oBACD,OAAO,GAAG,CAAC;gBACb,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC,CAAC,CAAC;YACH,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,KAAK,QAAQ,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACvF,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/audit/schema.d.ts

@@ -1,10 +1,3 @@
-/**
- * Audit record v1 — one JSON object per line in
- * ~/.local/state/things-api/audit/YYYY-MM.jsonl (see design §5).
- *
- * Every mutation ATTEMPT is recorded: successes, verification failures, and
- * blocked decisions (with invocation null — the app was never touched).
- */
 export interface AuditRecord {
     v: 1;
     ts: string;
@@ -26,13 +19,20 @@ export interface AuditRecord {
         id: string;
         role: "leg" | "summary";
     };
+    /**
+     * Undo back-reference (ADDITIVE): the undo token of the ORIGINAL mutation
+     * this record inverts. Set only on inverse mutations (`undo:<actor>` records)
+     * so a later `things undo --txn <token>` can tell an already-undone mutation
+     * apart from a nonexistent one. Absent on ordinary (non-undo) mutations.
+     */
+    undoOf?: string;
     /** Normalized requested delta (params as given, post-normalization). */
     requested: Record<string, unknown>;
     /** Asserted-field subset of the pre-state (null when target didn't exist). */
     pre: Record<string, unknown> | null;
     /** Post-verify observation (best-effort on failure). */
     observed: Record<string, unknown> | null;
-    result: "ok" | "verify-failed:timeout" | "verify-failed:mismatch" | "verify-failed:silent-noop" | `blocked:${string}` | "unsupported";
+    result: "intent" | "ok" | "verify-failed:timeout" | "verify-failed:mismatch" | "verify-failed:silent-noop" | `blocked:${string}` | "unsupported";
     verify: {
         attempts: number;
         elapsedMs: number;
@@ -44,3 +44,21 @@ export interface AuditRecord {
         fingerprint: "ok" | "drift" | "user-accepted" | "unknown";
     };
 }
+/**
+ * The stable UNDO TOKEN for a mutation — the value a caller passes to
+ * `things undo --txn <token>` (MCP `txn`) to invert exactly THIS record,
+ * immune to interleaving. Two cases:
+ *
+ *  - A compound operation's SUMMARY record already carries a real transaction
+ *    id shared by its legs — that id IS the token (undoing it replays the
+ *    whole sequence as one unit).
+ *  - A single-op record has no such id, so we derive a content-addressed one
+ *    from the fields that identify the record on disk (start timestamp + op +
+ *    actor + host + target uuid). The mutation lock serializes writes, so those
+ *    fields are unique per record in practice; the token is deterministic, so
+ *    the write path (which returns it in the result) and the undo path (which
+ *    recomputes it while scanning the trail) always agree.
+ *
+ * Purely additive: it is DERIVED from persisted fields, never stored.
+ */
+export declare function undoToken(record: Pick<AuditRecord, "ts" | "op" | "actor" | "host" | "uuid" | "txn">): string;

package/dist/audit/schema.js

@@ -4,6 +4,47 @@
  *
  * Every mutation ATTEMPT is recorded: successes, verification failures, and
  * blocked decisions (with invocation null — the app was never touched).
+ *
+ * A successful mutation writes TWO records: an `intent` marker immediately
+ * before the app is touched (M3 durability — so a crash between the app-side
+ * mutation and the final record leaves evidence the change may have landed),
+ * then the final `ok`/`verify-failed:*` record after read-after-write. The two
+ * share ts+op+actor+host (both derive from the same startedAt); an intent with
+ * no later final sibling is the signature of a crashed write. Intent records
+ * are NEVER undo targets — every undo reader filters `result === "ok"`, which
+ * an intent (result `"intent"`) is not, so it is excluded uniformly.
+ */
+import { createHash } from "node:crypto";
+/**
+ * The stable UNDO TOKEN for a mutation — the value a caller passes to
+ * `things undo --txn <token>` (MCP `txn`) to invert exactly THIS record,
+ * immune to interleaving. Two cases:
+ *
+ *  - A compound operation's SUMMARY record already carries a real transaction
+ *    id shared by its legs — that id IS the token (undoing it replays the
+ *    whole sequence as one unit).
+ *  - A single-op record has no such id, so we derive a content-addressed one
+ *    from the fields that identify the record on disk (start timestamp + op +
+ *    actor + host + target uuid). The mutation lock serializes writes, so those
+ *    fields are unique per record in practice; the token is deterministic, so
+ *    the write path (which returns it in the result) and the undo path (which
+ *    recomputes it while scanning the trail) always agree.
+ *
+ * Purely additive: it is DERIVED from persisted fields, never stored.
  */
-export {};
+export function undoToken(record) {
+    if (record.txn?.role === "summary")
+        return record.txn.id;
+    // JSON-encode the identity tuple so field boundaries are unambiguous (no
+    // separator an actor/host string could forge) while staying plain text.
+    const identity = JSON.stringify([
+        record.ts,
+        record.op,
+        record.actor,
+        record.host,
+        record.uuid ?? "",
+    ]);
+    const digest = createHash("sha256").update(identity).digest("hex").slice(0, 12);
+    return `m-${digest}`;
+}
 //# sourceMappingURL=schema.js.map

package/dist/audit/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/audit/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/audit/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAkDzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CACvB,MAA0E;IAE1E,IAAI,MAAM,CAAC,GAAG,EAAE,IAAI,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACzD,yEAAyE;IACzE,wEAAwE;IACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,KAAK;QACZ,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,IAAI,IAAI,EAAE;KAClB,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChF,OAAO,KAAK,MAAM,EAAE,CAAC;AACvB,CAAC"}

package/dist/cli/clock.d.ts

@@ -0,0 +1,8 @@
+export declare function setRenderClock(clock: {
+    now: () => Date;
+    zone: string | undefined;
+}): void;
+/** The render clock's instant (pinned THINGS_NOW when set, else real time); host time when unset. */
+export declare function renderNow(): Date;
+/** The render clock's consumer zone, or undefined for the host zone. */
+export declare function renderZone(): string | undefined;

package/dist/cli/clock.js

@@ -0,0 +1,24 @@
+/**
+ * The CLI's process-wide render clock, resolved once in `runCli` from the
+ * environment (THINGS_TZ / THINGS_NOW) and read by the pure renderers and the
+ * period parsers — the same module-state pattern the width fit uses
+ * (./width.ts). It carries the consumer's `now` source and IANA zone so every
+ * human date token (Today marker, ‹date› chips, period bounds) matches the
+ * `meta.clock` the library reports. Unset (the default, and in unit tests that
+ * import the renderers directly) it is the host clock — byte-identical output.
+ */
+let clockNow = null;
+let clockZone;
+export function setRenderClock(clock) {
+    clockNow = clock.now;
+    clockZone = clock.zone;
+}
+/** The render clock's instant (pinned THINGS_NOW when set, else real time); host time when unset. */
+export function renderNow() {
+    return clockNow === null ? new Date() : clockNow();
+}
+/** The render clock's consumer zone, or undefined for the host zone. */
+export function renderZone() {
+    return clockZone;
+}
+//# sourceMappingURL=clock.js.map

package/dist/cli/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/cli/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,IAAI,QAAQ,GAAwB,IAAI,CAAC;AACzC,IAAI,SAA6B,CAAC;AAElC,MAAM,UAAU,cAAc,CAAC,KAAoD;IACjF,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC;IACrB,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC;AACzB,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,SAAS;IACvB,OAAO,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;AACrD,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,UAAU;IACxB,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/cli/commands/area.d.ts

@@ -3,8 +3,8 @@
  * under `things area` are registered by writes.ts on the same group).
  */
 import type { Command } from "commander";
-import type { AreaView } from "../../read/area-view.ts";
-import { type GroupedLimits } from "../../read/pagination.ts";
+import { type AreaView, type GroupedLimits, type GroupedTruncation } from "../../index.ts";
+import { type TagFlags } from "../tag-filters.ts";
 export interface AreaShowOpts {
     showLater?: boolean;
     /** Commander optional-value flag: true when bare, the raw string when given a count. */
@@ -24,6 +24,29 @@ export interface AreaShowOpts {
  * (future-scheduled projects, to-dos, and repeating templates intermixed in
  * date order) and Someday (someday projects as a leading block, then
  * someday to-dos). `--show-logged` reveals the full logbook.
+ *
+ * `view` is the already-bounded card (its ACTIVE project rows and direct to-dos
+ * capped; scheduled/someday project rows and the later/logged/trashed sections
+ * intact) and `grouped` the per-block metadata carrying each capped section's
+ * pre-cap total — so the "… N more" footers derive from metadata, never a
+ * pre-cap copy of the view.
  */
-export declare function renderAreaView(view: AreaView, opts: AreaShowOpts): string[];
+export declare function renderAreaView(view: AreaView, grouped: GroupedTruncation, opts: AreaShowOpts): string[];
+/** Options accepted by the area-show code path (shared by `area show` and `areas <ref>`). */
+export type AreaShowActionOpts = AreaShowOpts & TagFlags & {
+    json?: boolean;
+    db?: string;
+    limit?: string;
+    areaLimit?: string;
+    projectLimit?: string;
+    all?: boolean;
+    /** Content scope: keep only rows (loose to-dos + child projects) with an overdue own deadline. */
+    overdue?: boolean;
+};
+/**
+ * The `area show <ref>` action body, factored out so the pluralized
+ * `things areas <ref>` can delegate to the identical code path (a true synonym,
+ * not a reimplementation). Both echo the canonical `things area show …` hint.
+ */
+export declare function runAreaShow(ref: string, opts: AreaShowActionOpts): void;
 export declare function registerAreaCommands(program: Command): void;