things-api 0.18.0 → 0.19.1

package/README.md

@@ -1,8 +1,10 @@
+<img src="assets/things-api-icon-160x160.png" alt="" width="80" height="80">
+
 # things-api
 
 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.18.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 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 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.
+**Status: read + write + MCP layers live and published to npm (v0.19.1 — 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
@@ -24,19 +26,26 @@ Most ways to script Things fire a URL or an AppleScript command and hope. This p
 
 ## 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; 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)
+Things 3 installed and launched once, Node ≥ 24, and a handful of one-time macOS consents / Things settings depending on what you use. **See [docs/setup.md](docs/setup.md)** — including the dedicated-automation-Mac checklist.
 
-A few operations exist on no other app surface: creating a heading in an **existing** project, clearing a reminder from a date-scheduled item, and permanently deleting a single item. These run through six bundled Apple Shortcuts (signed `.shortcut` files shipped with the package). Install them with:
+Run **one** of the two setup ceremonies and you are done:
 
 ```sh
-things setup shortcuts   # opens an install sheet per missing shortcut — click "Add Shortcut"
+things setup           # grants attach to this terminal (or agent harness)
+things helpers setup   # grants attach to a signed helper pair instead
 ```
 
-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.
+Both settle everything in one sitting — read access to the Things data folder, permission to control the Things app, and the bundled shortcuts — skipping anything already granted, resuming exactly where they left off, and exiting nonzero while anything is outstanding. `things setup` is the quick path; `things helpers setup` is the durable one, because the grants stop being re-requested every time your terminal updates. Which one you have is reported by `things doctor` and summarized in `things --help`.
+
+Outside those two commands **nothing in this package will ever put a macOS permission dialog on your screen**: every entry point works out what it is allowed to do using checks that cannot prompt, and refuses with the exact remediation instead. That is a hard contract, described in [docs/design/permissions-doctrine.md](docs/design/permissions-doctrine.md) — a dialog raised anywhere else is a bug. Handing an explicit `--db <path>` (a Desktop copy, a backup) opts out of all of it: plain file semantics, ordinary errors.
+
+### The bundled Shortcuts
+
+A few operations exist on no other app surface: creating a heading in an **existing** project, clearing a reminder from a date-scheduled item, and permanently deleting a single item. These run through six bundled Apple Shortcuts (signed `.shortcut` files shipped with the package), installed as one leg of `things setup` — it opens an install sheet per missing shortcut; click "Add Shortcut" on each.
+
+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 --dry-run` and `things doctor` report installation state without asking for anything.
 
-Once installed, these Shortcuts-only operations become available as ordinary commands: `things project add-heading <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 add-heading 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.
+Once installed, these Shortcuts-only operations become available as ordinary commands: `things project add-heading <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 add-heading action, and `clear_reminder`). If a required shortcut is missing, the command is blocked up front with a pointer back to `things setup` — nothing is dispatched.
 
 ### Accessibility GUI vector (optional, off by default)
 
@@ -141,6 +150,6 @@ The catalog is consolidated around a few verb-parameterized tools (a discriminat
 - **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 56-op catalog), `batch`, `reorder` (item ordering across scopes, plus `scope=areas` for the sidebar area order), `undo`, `capabilities`, `doctor`.
+- **Generic & discovery**: `run_operation` (the full 57-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/deputy/VERSION

@@ -1 +1 @@
-1.1.0
+1.3.0

package/deputy/helpers-Info.plist

@@ -17,6 +17,10 @@
   <string>APPL</string>
   <key>CFBundleShortVersionString</key>
   <string>0.0.0</string>
+  <!-- Original artwork, drawn by scripts/generate-helper-icon.jxa — the icon
+       System Settings shows next to the Automation/Accessibility toggles. -->
+  <key>CFBundleIconFile</key>
+  <string>AppIcon</string>
   <key>LSUIElement</key>
   <true/>
 </dict>

package/deputy/prebuilt/Things API Helper.app/Contents/Helpers/things-reader.app/Contents/Info.plist

@@ -12,8 +12,10 @@
   <string>things-reader</string>
   <key>CFBundlePackageType</key>
   <string>APPL</string>
+  <key>CFBundleIconFile</key>
+  <string>AppIcon</string>
   <key>CFBundleShortVersionString</key>
-  <string>1.1.0</string>
+  <string>1.3.0</string>
   <key>LSUIElement</key>
   <true/>
 </dict>

package/deputy/prebuilt/Things API Helper.app/Contents/Helpers/things-reader.app/Contents/_CodeSignature/CodeResources

@@ -3,9 +3,22 @@
 <plist version="1.0">
 <dict>
 	<key>files</key>
-	<dict/>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<data>
+		9VX5ZsSdgBEnhGRQvzKyEjHvzeM=
+		</data>
+	</dict>
 	<key>files2</key>
-	<dict/>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			li4eVDJT2l1+UncvB0nWNrYjSQliN87HTz3w1j2kG3A=
+			</data>
+		</dict>
+	</dict>
 	<key>rules</key>
 	<dict>
 		<key>^Resources/</key>

package/deputy/prebuilt/Things API Helper.app/Contents/Info.plist

@@ -16,7 +16,11 @@
   <key>CFBundlePackageType</key>
   <string>APPL</string>
   <key>CFBundleShortVersionString</key>
-  <string>1.1.0</string>
+  <string>1.3.0</string>
+  <!-- Original artwork, drawn by scripts/generate-helper-icon.jxa — the icon
+       System Settings shows next to the Automation/Accessibility toggles. -->
+  <key>CFBundleIconFile</key>
+  <string>AppIcon</string>
   <key>LSUIElement</key>
   <true/>
 </dict>

package/deputy/prebuilt/Things API Helper.app/Contents/_CodeSignature/CodeResources

@@ -3,18 +3,30 @@
 <plist version="1.0">
 <dict>
 	<key>files</key>
-	<dict/>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<data>
+		9VX5ZsSdgBEnhGRQvzKyEjHvzeM=
+		</data>
+	</dict>
 	<key>files2</key>
 	<dict>
 		<key>Helpers/things-reader.app</key>
 		<dict>
 			<key>cdhash</key>
 			<data>
-			ya8H6K5Zoo9Zq8pTP3Aum+20ZI0=
+			DCwtQKeK2+xh4Jh2U4b6UU9KZv4=
 			</data>
 			<key>requirement</key>
 			<string>identifier "com.pixelcog.things-reader" and anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = VNJWARH2W7</string>
 		</dict>
+		<key>Resources/AppIcon.icns</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			li4eVDJT2l1+UncvB0nWNrYjSQliN87HTz3w1j2kG3A=
+			</data>
+		</dict>
 	</dict>
 	<key>rules</key>
 	<dict>

package/deputy/reader/Info.plist

@@ -12,6 +12,8 @@
   <string>things-reader</string>
   <key>CFBundlePackageType</key>
   <string>APPL</string>
+  <key>CFBundleIconFile</key>
+  <string>AppIcon</string>
   <key>CFBundleShortVersionString</key>
   <string>0.0.0</string>
   <key>LSUIElement</key>

package/deputy/reader/entitlements.plist

@@ -11,5 +11,35 @@
   <true/>
   <key>com.apple.security.files.bookmarks.app-scope</key>
   <true/>
+  <!-- The ONE path outside the container the reader may touch: its rendezvous
+       directory, where it binds the client-facing socket. launchd Sockets
+       activation is unusable from inside the sandbox (error 159, measured
+       2026-08-24), so the reader binds the socket itself under this exception.
+       Scoped to a single dot-directory subtree; notarization accepts
+       temporary-exceptions on Developer ID builds. -->
+  <!-- MEASURED 2026-08-24: with the file exception alone, plain file writes in
+       the rendezvous dir SUCCEED while bind(2) is denied EPERM — unix-socket
+       binding is the sandbox's network-bind operation class, path-filtered to
+       the container, and network.server does not extend it. The raw-SBPL
+       temporary exception below is the one public lever that does. -->
+  <!-- Unix-socket bind is the sandbox's network-bind operation class, path-
+       filtered to the container — MEASURED 2026-08-24: with the file exception
+       alone, file writes in the rendezvous dir succeed while bind(2) is EPERM,
+       and `network.server` does not extend it. This raw-SBPL exception is the
+       one public lever that does. Grammar is picky (also measured): a
+       `(subpath ...)` filter compiles; a regex filter and the bare
+       `(allow network-bind network-listen)` form both make sandbox
+       initialization TRAP at spawn (SIGTRAP, and launchd bootstrap fails 5).
+       "/Users" because entitlements are baked at signing and must serve any
+       user's home; the reader's practical reach stays scoped by the file
+       exception above (it can only create the socket where it can write). -->
+  <key>com.apple.security.temporary-exception.sbpl</key>
+  <array>
+    <string>(allow network-bind (subpath "/Users"))</string>
+  </array>
+  <key>com.apple.security.temporary-exception.files.home-relative-path.read-write</key>
+  <array>
+    <string>/.local/state/things-api/reader/</string>
+  </array>
 </dict>
 </plist>

package/deputy/reader/main.swift

@@ -18,11 +18,35 @@
  *
  * Ships as a minimal .app bundle (secinit refuses bare executables) signed
  * with a real certificate chain (amfid refuses ad-hoc on sandboxed code).
- * State (bookmark, token, socket, log) lives in the sandbox container home.
+ *
+ * ── The rendezvous lives OUTSIDE this container (helpers 1.3.0) ─────────────
+ *
+ * A sandboxed process can only bind a socket inside its own container home, so
+ * for as long as this process bound its own socket, every CLIENT stat/open of
+ * that socket was a cross-app container access — the
+ * kTCCServiceSystemPolicyAppData consent class, silent under a Full-Disk-Access
+ * host and a modal from anywhere else. That made reader routing per-host, which
+ * is the opposite of what the helper pair exists for.
+ *
+ * So the rendezvous lives OUTSIDE the container, in the user's own state dir:
+ *
+ *   • the SOCKET is bound by THIS process at the host-neutral path injected via
+ *     THINGS_READER_SOCKET — the sandbox permits it through a
+ *     home-relative-path temporary-exception entitlement scoped to that one
+ *     directory. (launchd `Sockets` activation was tried first and FAILS from
+ *     inside the App Sandbox with error 159 "Sandbox restriction", measured
+ *     2026-08-24 — do not re-attempt it.) No fallback paths: without the env
+ *     this process exits, loudly;
+ *   • the TOKEN it expects arrives in THINGS_READER_TOKEN, injected into the
+ *     same plist by the installer, which writes the matching file for clients.
+ *
+ * What stays in the container is what was always right to keep there: the
+ * security-scoped BOOKMARK (the read grant itself, reader-internal, never read
+ * by a client) and the audit log.
  *
  * Modes:
  *   --grant <startDir>   present the NSOpenPanel ceremony, save the bookmark
- *   --serve              serve the socket (launchd mode; default)
+ *   --serve              bind and serve the rendezvous socket (default)
  *   --version            print the version
  */
 import AppKit
@@ -34,17 +58,48 @@ let READER_PROTOCOL_VERSION = 1
 let MAX_LINE_BYTES = 8 * 1024 * 1024
 let MAX_FILE_READ_BYTES = 64 * 1024 * 1024
 
+/// The env var the LaunchAgent carries the expected access token in.
+let READER_TOKEN_ENV = "THINGS_READER_TOKEN"
+
 // Sandboxed home == the container Data dir — the durable private store.
 let home = NSHomeDirectory()
 let bookmarkFile = home + "/things-reader.bookmark"
-let socketPath = home + "/reader.sock"
-let tokenFile = home + "/token"
 let logFile = home + "/reader.log"
+// Pre-1.3.0 the socket and token lived here. Only this process can delete them
+// (they are inside its container), so it does — see cleanUpLegacyRendezvous().
+let legacySocketPath = home + "/reader.sock"
+let legacyTokenFile = home + "/token"
 
 func stderrLine(_ message: String) {
   FileHandle.standardError.write(Data("things-reader: \(message)\n".utf8))
 }
 
+/**
+ * The rendezvous socket path, injected by the installer into the LaunchAgent.
+ * launchd socket activation is NOT usable here — MEASURED 2026-08-24 on this
+ * exact bundle: `launch_activate_socket` fails with 159 ("Sandbox restriction")
+ * from inside the App Sandbox, so the reader binds the socket ITSELF at a
+ * host-neutral path its entitlements grant
+ * (the home-relative-path file exception for the rendezvous dir, plus the
+ * raw-SBPL `(allow network-bind (subpath "/Users"))` — unix bind is the
+ * sandbox's network-bind class, which file exceptions alone do not grant;
+ * see entitlements.plist for the measured grammar). Clients reach the socket
+ * with no TCC class.
+ */
+let READER_SOCKET_ENV = "THINGS_READER_SOCKET"
+
+/**
+ * Delete the pre-1.3.0 in-container rendezvous. Those files are dead the moment
+ * this build runs — nothing binds or reads them any more — and this process is
+ * the ONLY one that can remove them, since they sit in its sandbox container
+ * and a client touching that path is the very consent class 1.3.0 escaped.
+ * Idempotent; a fresh install finds nothing.
+ */
+func cleanUpLegacyRendezvous() {
+  unlink(legacySocketPath)
+  unlink(legacyTokenFile)
+}
+
 // --- grant ceremony ---
 
 func runGrant(startDir: String) -> Never {
@@ -126,19 +181,6 @@ let scope = Scope()
 
 // --- server (file verbs only) ---
 
-func loadOrCreateToken() -> String {
-  if let data = FileManager.default.contents(atPath: tokenFile) {
-    let tok = String(decoding: data, as: UTF8.self).trimmingCharacters(in: .whitespacesAndNewlines)
-    if !tok.isEmpty { return tok }
-  }
-  var bytes = [UInt8](repeating: 0, count: 32)
-  for i in 0..<bytes.count { bytes[i] = UInt8.random(in: 0...255) }
-  let tok = bytes.map { String(format: "%02x", $0) }.joined()
-  FileManager.default.createFile(
-    atPath: tokenFile, contents: Data(tok.utf8), attributes: [.posixPermissions: 0o600])
-  return tok
-}
-
 /// How long a shutting-down reader waits for requests already in flight (the
 /// deputy's DRAIN_TIMEOUT_SECONDS; the two halves are booted out together).
 let READER_DRAIN_TIMEOUT_SECONDS: TimeInterval = 10
@@ -173,17 +215,41 @@ final class ReaderServer {
     cacheLock.unlock()
   }
 
-  func run() {
+  private var socketPath: String = ""
+
+  /**
+   * Bind and serve the rendezvous socket at the host-neutral path the
+   * installer injected. The sandbox permits the bind through the reader's
+   * home-relative-path entitlement; launchd activation is unusable from
+   * inside the sandbox (error 159, measured — see the header).
+   */
+  func run(socketPath path: String) {
+    socketPath = path
+    // Boot diagnostic: discriminate a file-rule failure (entitlement form/path
+    // wrong) from a bind-rule failure (operation class) when the bind below
+    // fails. Removed file, one line, only on failure.
+    let probePath = (path as NSString).deletingLastPathComponent + "/.write-probe"
+    if FileManager.default.createFile(atPath: probePath, contents: Data("x".utf8)) {
+      unlink(probePath)
+    } else {
+      stderrLine("write-probe FAILED in rendezvous dir — the file entitlement is not covering it")
+    }
     let fd = socket(AF_UNIX, SOCK_STREAM, 0)
-    guard fd >= 0 else { fatalDie("socket() errno \(errno)") }
+    guard fd >= 0 else {
+      stderrLine("socket() errno \(errno)")
+      exit(78)
+    }
     listenFd = fd
-    unlink(socketPath)
+    unlink(path)
     var addr = sockaddr_un()
     addr.sun_family = sa_family_t(AF_UNIX)
     let capacity = MemoryLayout.size(ofValue: addr.sun_path)
-    guard socketPath.utf8.count < capacity else { fatalDie("socket path too long: \(socketPath)") }
+    guard path.utf8.count < capacity else {
+      stderrLine("socket path too long: \(path)")
+      exit(78)
+    }
     _ = withUnsafeMutablePointer(to: &addr.sun_path) { ptr in
-      socketPath.withCString { cstr in
+      path.withCString { cstr in
         strncpy(UnsafeMutableRawPointer(ptr).assumingMemoryBound(to: CChar.self), cstr, capacity - 1)
       }
     }
@@ -192,9 +258,16 @@ final class ReaderServer {
         bind(fd, sa, socklen_t(MemoryLayout<sockaddr_un>.size))
       }
     }
-    guard bound == 0 else { fatalDie("bind(\(socketPath)) errno \(errno)") }
-    chmod(socketPath, 0o600)
-    guard listen(fd, 16) == 0 else { fatalDie("listen() errno \(errno)") }
+    guard bound == 0 else {
+      stderrLine(
+        "bind(\(path)) errno \(errno) — the reader's sandbox entitlement must cover this path; run `things helpers setup`")
+      exit(78)
+    }
+    chmod(path, 0o600)
+    guard listen(fd, 16) == 0 else {
+      stderrLine("listen() errno \(errno)")
+      exit(78)
+    }
     audit(["event": "started", "pid": Int(getpid()), "version": DEPUTY_VERSION])
     while true {
       let conn = accept(fd, nil, nil)
@@ -214,18 +287,14 @@ final class ReaderServer {
     }
   }
 
-  private func fatalDie(_ message: String) -> Never {
-    stderrLine(message)
-    exit(1)
-  }
-
   /**
-   * Graceful drain, then teardown (mirrors the deputy): remove the socket path
-   * so no new client can find us, close the listener, wait out the in-flight
-   * requests within a bound, flush the log. SIGKILL is still the hard stop.
+   * Graceful drain, then teardown — the deputy's semantics: unlink the socket
+   * FIRST (the deterministic accept-wake, and it stops new clients dialing a
+   * dying process), finish in-flight requests within the bound, flush the log.
+   * SIGKILL is the hard stop.
    */
   func drainAndShutdown(timeout: TimeInterval = READER_DRAIN_TIMEOUT_SECONDS) {
-    unlink(socketPath)
+    if !socketPath.isEmpty { unlink(socketPath) }
     if listenFd >= 0 {
       Darwin.shutdown(listenFd, SHUT_RDWR)
       close(listenFd)
@@ -303,7 +372,7 @@ final class ReaderServer {
       return errorResponse(id: id, code: "unsupported-protocol", message: "reader speaks protocol \(READER_PROTOCOL_VERSION)")
     }
     guard let reqToken = obj["token"] as? String, reqToken == token else {
-      return errorResponse(id: id, code: "bad-token", message: "request token does not match the reader token file")
+      return errorResponse(id: id, code: "bad-token", message: "request token does not match the reader's access token")
     }
     guard let verb = obj["verb"] as? String else {
       return errorResponse(id: id, code: "bad-request", message: "missing verb")
@@ -354,7 +423,7 @@ final class ReaderServer {
         nil,
         errorResponse(
           id: id, code: "not-granted",
-          message: "no security-scoped grant yet — run `things helpers grant` and select the Things data folder")
+          message: "no security-scoped grant yet — run `things helpers setup` and select the Things data folder")
       )
     }
     return (root, nil)
@@ -467,7 +536,27 @@ case "--grant":
   }
   runGrant(startDir: arguments[2])
 case "--serve":
-  let server = ReaderServer(token: loadOrCreateToken())
+  // No fallbacks, deliberately: both the token and the listening socket come
+  // from the LaunchAgent, so a --serve outside it is a misconfiguration to
+  // surface, never a second code path to keep working. EX_CONFIG (78).
+  guard let token = ProcessInfo.processInfo.environment[READER_TOKEN_ENV], !token.isEmpty else {
+    stderrLine(
+      "\(READER_TOKEN_ENV) is not set — the access token is injected by the reader's LaunchAgent; run `things helpers setup`")
+    exit(78)
+  }
+  guard let socketPath = ProcessInfo.processInfo.environment[READER_SOCKET_ENV],
+    !socketPath.isEmpty
+  else {
+    stderrLine(
+      "\(READER_SOCKET_ENV) is not set — the rendezvous path is injected by the reader's LaunchAgent; run `things helpers setup`")
+    exit(78)
+  }
+  // 1.3.0 migration, and only on a real boot — the refusals above must stay
+  // side-effect-free, so nothing is deleted until launchd has actually
+  // activated us. Idempotent, so paying it every boot costs two failed
+  // unlink(2)s.
+  cleanUpLegacyRendezvous()
+  let server = ReaderServer(token: token)
   signal(SIGPIPE, SIG_IGN)
   signal(SIGTERM, SIG_IGN)
   signal(SIGINT, SIG_IGN)
@@ -476,14 +565,14 @@ case "--serve":
   for source in [termSource, intSource] {
     source.setEventHandler {
       // Graceful drain: stop accepting, finish in-flight reads within a bound,
-      // then remove the socket and exit cleanly (an upgrade boots both halves
-      // out mid-flight).
+      // then exit cleanly (an upgrade boots both halves out mid-flight). The
+      // socket itself is launchd's and outlives us.
       server.drainAndShutdown()
       exit(0)
     }
     source.resume()
   }
-  Thread.detachNewThread { server.run() }
+  Thread.detachNewThread { server.run(socketPath: socketPath) }
   dispatchMain()
 default:
   stderrLine("usage: things-reader --serve | --grant <dir> | --version")

package/deputy/src/server.swift

@@ -12,7 +12,7 @@
 import Foundation
 
 /// How long a shutting-down deputy waits for requests already in flight. An
-/// upgrade (`things helpers install` / `restart`) boots the old process out
+/// upgrade (`things helpers setup` / `restart`) boots the old process out
 /// mid-flight; without a drain the in-flight request dies with it. launchd's
 /// own bootout wait, and the CLI's `launchctl` timeout, both clear this bound.
 let DRAIN_TIMEOUT_SECONDS: TimeInterval = 10
@@ -212,6 +212,8 @@ final class Server {
     switch verb {
     case "hello":
       result = handleHello(id: id)
+    case "prime-ax":
+      result = handlePrimeAx(id: id)
     case "osascript":
       guard let script = obj["script"] as? String else {
         result = errorResponse(id: id, code: "bad-request", message: "osascript verb requires a script string")
@@ -275,7 +277,7 @@ final class Server {
       // File verbs live exclusively on the sandboxed things-reader.
       result = errorResponse(
         id: id, code: "unsupported-verb",
-        message: "the deputy serves automation verbs only — file access rides things-reader (things helpers grant)")
+        message: "the deputy serves automation verbs only — file access rides things-reader (things helpers setup)")
     default:
       result = errorResponse(id: id, code: "bad-request", message: "unknown verb \(verb)")
     }
@@ -312,6 +314,13 @@ final class Server {
 
   // --- verb handlers ---
 
+  /**
+   * The handshake, plus the deputy's own TCC standing — Accessibility trust
+   * and Automation permission for each target it drives. Every field here is
+   * PROMPT-FREE by construction (see tcc.swift), which is what lets a status
+   * report and the onboarding ceremony ask "is this leg already granted?"
+   * without raising a dialog at whoever happens to run `things` next.
+   */
   private func handleHello(id: Any?) -> [String: Any] {
     [
       "id": id ?? NSNull(),
@@ -321,9 +330,23 @@ final class Server {
       "role": "deputy",
       "pid": Int(getpid()),
       "uptimeMs": Int(Date().timeIntervalSince(startedAt) * 1000),
+      "axTrusted": accessibilityTrusted(),
+      "automation": [
+        "things": automationStatus(bundleID: "com.culturedcode.ThingsMac"),
+        "systemEvents": automationStatus(bundleID: "com.apple.systemevents"),
+      ],
     ]
   }
 
+  /**
+   * Raise the Accessibility consent dialog for the deputy's own identity. The
+   * grant itself is a toggle in System Settings, so the answer can only arrive
+   * later — the caller polls `hello`'s axTrusted. Returns the state as of now.
+   */
+  private func handlePrimeAx(id: Any?) -> [String: Any] {
+    ["id": id ?? NSNull(), "ok": true, "axTrusted": primeAccessibility()]
+  }
+
   // --- audit log ---
 
   private func audit(_ entry: [String: Any]) {

package/deputy/src/tcc.swift

@@ -0,0 +1,58 @@
+/**
+ * Prompt-free TCC introspection, plus the one call that deliberately DOES
+ * prompt (Accessibility).
+ *
+ * The deputy is the process macOS attributes every AppleEvent and every
+ * Accessibility action to, so it — and only it — can answer "am I allowed to
+ * drive Things?" truthfully. Both answers ride the `hello` response, which
+ * makes `things helpers status` and the onboarding ceremony able to SKIP a leg
+ * that is already granted instead of re-firing a dialog at the user.
+ *
+ * `AEDeterminePermissionToAutomateTarget(…, askUserIfNeeded: false)` is the
+ * documented non-prompting probe: it answers from the existing TCC record and
+ * returns errAEEventWouldRequireUserConsent (-1744) when no record exists yet
+ * — reported here as "unknown", which is exactly the state the ceremony then
+ * resolves by sending a real (prompting) AppleEvent.
+ */
+import ApplicationServices
+import Foundation
+
+/// One target's Automation state: "granted" | "denied" | "not-running" | "unknown".
+func automationStatus(bundleID: String) -> String {
+  var target = AEAddressDesc()
+  let bytes = Array(bundleID.utf8)
+  let created = bytes.withUnsafeBufferPointer { buf in
+    AECreateDesc(typeApplicationBundleID, buf.baseAddress, buf.count, &target)
+  }
+  guard created == noErr else { return "unknown" }
+  defer { AEDisposeDesc(&target) }
+  // askUserIfNeeded: false — a status probe must never raise a dialog.
+  let status = AEDeterminePermissionToAutomateTarget(&target, typeWildCard, typeWildCard, false)
+  switch status {
+  case noErr:
+    return "granted"
+  case -1743:  // errAEEventNotPermitted — the user (or MDM) said no.
+    return "denied"
+  case -600:  // procNotFound — the target is not running, so TCC has no answer.
+    return "not-running"
+  default:
+    // -1744 errAEEventWouldRequireUserConsent lands here: never asked yet.
+    return "unknown"
+  }
+}
+
+/// Accessibility trust for THIS process, prompt-free.
+func accessibilityTrusted() -> Bool {
+  AXIsProcessTrusted()
+}
+
+/**
+ * Ask macOS to show the Accessibility prompt for this process. The dialog is
+ * fire-and-forget (it offers a Settings deep-link; the actual grant is a
+ * toggle the user flips in System Settings), so this returns the CURRENT trust
+ * state immediately rather than waiting for one that can only arrive later.
+ */
+func primeAccessibility() -> Bool {
+  let key = kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String
+  return AXIsProcessTrustedWithOptions([key: true] as CFDictionary)
+}