things-api 0.18.0 → 0.19.0

package/dist/deputy/install.js

@@ -13,18 +13,37 @@
  * bookmark grant and must never change.
  */
 import { execFileSync, spawnSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { loadConfig, saveConfigKey } from "../config.js";
 import { THINGS_GROUP_CONTAINER } from "../db/locate.js";
+import { readRendezvousToken, rendezvousExists } from "../host-access.js";
+import { createWizard, withDefaultInterrupts } from "../wizard.js";
+import { EXPECTED_PROXIES } from "../write/availability.js";
 import { DeputySyncBridge } from "./bridge.js";
-import { DEPUTY_LAUNCHD_LABEL, HELPERS_BUNDLE_ID, READER_LAUNCHD_LABEL, DEPUTY_PROTOCOL_VERSION, deputyInstalledBinaryPath, deputySocketPath, deputyStateDir, deputyTokenPath, helpersInstallDir, helpersInstalledBundlePath, readerInstalledAppPath, readerSocketPath, readerTokenPath, } from "./protocol.js";
-export function deputyPlistPath() {
-    return join(homedir(), "Library/LaunchAgents", `${DEPUTY_LAUNCHD_LABEL}.plist`);
+import { DEPUTY_LAUNCHD_LABEL, HELPERS_BUNDLE_ID, READER_LAUNCHD_LABEL, DEPUTY_PROTOCOL_VERSION, DeputyRequestError, deputyInstalledBinaryPath, deputySocketPath, deputyStateDir, deputyTokenPath, EXPECTED_HELPERS_VERSION, helpersInstallDir, helpersInstalledBundlePath, readerInstalledAppPath, readerRendezvousDir, readerSandboxContainerDir, readerSocketPath, READER_SOCKET_ENV, readerTokenPath, READER_TOKEN_ENV, } from "./protocol.js";
+/**
+ * Where the LaunchAgent plists live. THINGS_API_LAUNCH_AGENTS_DIR overrides
+ * for tests — WITHOUT it, every suite that exercises install/uninstall/reset
+ * mutates the DEVELOPER MACHINE's real ~/Library/LaunchAgents. That is not
+ * hypothetical: it deleted the live helpers' plists mid-`npm run check`
+ * twice on 2026-08-24 before this seam existed. Test setup must always set
+ * it alongside THINGS_API_STATE_DIR.
+ */
+export function launchAgentsDir(env = process.env) {
+    const explicit = env["THINGS_API_LAUNCH_AGENTS_DIR"];
+    if (explicit !== undefined && explicit !== "")
+        return explicit;
+    return join(homedir(), "Library/LaunchAgents");
 }
-export function readerPlistPath() {
-    return join(homedir(), "Library/LaunchAgents", `${READER_LAUNCHD_LABEL}.plist`);
+export function deputyPlistPath(env = process.env) {
+    return join(launchAgentsDir(env), `${DEPUTY_LAUNCHD_LABEL}.plist`);
+}
+export function readerPlistPath(env = process.env) {
+    return join(launchAgentsDir(env), `${READER_LAUNCHD_LABEL}.plist`);
 }
 /**
  * Where an install looks for the bundle when the caller names no path, in
@@ -74,7 +93,23 @@ function readerLaunchTarget() {
 function readerExecPath(appPath) {
     return join(appPath, "Contents/MacOS/things-reader");
 }
-function renderReaderPlist(appPath) {
+/**
+ * The reader's LaunchAgent. Two keys carry the whole host-universal rendezvous:
+ *
+ * - **`Sockets`** — launchd creates, binds, listens on and chmods the socket at
+ *   `socketPath`, which is OUR state directory, and hands the sandboxed reader
+ *   the already-listening fd at activation (`launch_activate_socket`). The
+ *   reader cannot bind outside its container, so launchd binding on its behalf
+ *   is the only way the rendezvous escapes it — and with the socket outside
+ *   every container, a client reaching it crosses no consent class.
+ * - **`EnvironmentVariables`** — the access token, minted by the installer and
+ *   written to a sibling file for clients. Delivering it through the plist is
+ *   what lets the reader keep its expected token out of the container too.
+ *
+ * The plist therefore CARRIES A SECRET and is written 0600 — the same
+ * same-user trust class as the token file itself.
+ */
+export function renderReaderPlist(appPath, socketPath, token) {
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -90,6 +125,21 @@ function renderReaderPlist(appPath) {
   <true/>
   <key>KeepAlive</key>
   <true/>
+  <key>StandardErrorPath</key>
+  <string>${dirname(socketPath)}/reader.stderr.log</string>
+  <!-- The rendezvous path and access token, minted/chosen by install. The
+       reader BINDS the socket itself at this host-neutral path — its sandbox
+       entitlement covers exactly this directory. launchd Sockets activation
+       is NOT usable: launch_activate_socket fails with 159 "Sandbox
+       restriction" inside the App Sandbox (measured 2026-08-24). This file is
+       written 0600 because of the token. -->
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>${READER_SOCKET_ENV}</key>
+    <string>${socketPath}</string>
+    <key>${READER_TOKEN_ENV}</key>
+    <string>${token}</string>
+  </dict>
   <!-- Background Task Management groups the login item under the helper
        bundle's display name ("Things API Helper") instead of the signing
        certificate's personal name. -->
@@ -101,10 +151,52 @@ function renderReaderPlist(appPath) {
 </plist>
 `;
 }
+/**
+ * Mint the reader's access token and lay down the client half of the
+ * rendezvous: `<state>/reader`, 0700, holding a 0600 token file. Returns the
+ * token so the same value can be injected into the LaunchAgent.
+ *
+ * The installer mints it — not the reader — because the reader can only write
+ * inside its container, which is the placement this whole arrangement exists
+ * to leave. A fresh token per install is deliberate: install owns the pair
+ * wholesale, and rotating the secret costs nothing when both ends are rewritten
+ * in the same breath.
+ */
+export function mintReaderRendezvous(env) {
+    const dir = readerRendezvousDir(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    const token = randomBytes(32).toString("hex");
+    const tokenPath = readerTokenPath(env);
+    writeFileSync(tokenPath, token, { mode: 0o600 });
+    // writeFileSync's mode applies on CREATE only — an existing file keeps
+    // whatever it had, so the chmod is the one that actually holds the line.
+    chmodSync(tokenPath, 0o600);
+    // launchd binds the socket itself and refuses when something already sits at
+    // the path (a plain file left by an older layout, or a socket from a job it
+    // no longer tracks). Clearing it is safe: we booted the reader out above.
+    try {
+        unlinkSync(readerSocketPath(env));
+    }
+    catch {
+        // ENOENT is the ordinary case.
+    }
+    return token;
+}
 function launchTarget() {
     return `gui/${process.getuid?.() ?? 501}/${DEPUTY_LAUNCHD_LABEL}`;
 }
 function launchctl(args) {
+    // The other half of the test blast-shield: with the LaunchAgents dir
+    // redirected, real launchctl calls would still act on the REAL jobs while
+    // the plists are fakes — tests booted the live helpers out mid-check on
+    // 2026-08-24 exactly this way. Under the override, launchctl is inert.
+    if ((process.env["THINGS_API_LAUNCH_AGENTS_DIR"] ?? "") !== "") {
+        return {
+            ok: false,
+            output: "launchctl disabled under THINGS_API_LAUNCH_AGENTS_DIR (test shield)",
+        };
+    }
     try {
         // stderr must be captured, never inherited: a routine negative probe
         // ("Could not find service … in domain") is a state we REPORT, not noise
@@ -181,9 +273,11 @@ export function deputySigningInfo(binaryPath) {
 function readerHelloProbe(env) {
     const socketPath = readerSocketPath(env);
     const tokenPath = readerTokenPath(env);
-    if (!existsSync(socketPath) || !existsSync(tokenPath))
+    if (!rendezvousExists(socketPath) || !rendezvousExists(tokenPath))
+        return null;
+    const token = readRendezvousToken(tokenPath);
+    if (token === null)
         return null;
-    const token = readFileSync(tokenPath, "utf8").trim();
     const bridge = new DeputySyncBridge(socketPath);
     try {
         const res = bridge.request({ v: DEPUTY_PROTOCOL_VERSION, token, verb: "hello" }, 2000);
@@ -222,7 +316,7 @@ export function installHelpers(options = {}, env = process.env) {
     rmSync(installDir, { recursive: true, force: true });
     mkdirSync(installDir, { recursive: true, mode: 0o700 });
     cpSync(source, bundlePath, { recursive: true });
-    const plistPath = deputyPlistPath();
+    const plistPath = deputyPlistPath(env);
     mkdirSync(dirname(plistPath), { recursive: true });
     writeFileSync(plistPath, renderPlist(deputyInstalledBinaryPath(env), stateDir));
     const warnings = [];
@@ -237,8 +331,12 @@ export function installHelpers(options = {}, env = process.env) {
     }
     let readerGranted = null;
     if (readerInBuild) {
-        const readerPlist = readerPlistPath();
-        writeFileSync(readerPlist, renderReaderPlist(readerInstalledAppPath(env)));
+        // The rendezvous is minted BEFORE the plist is written: the plist carries
+        // the same token, so the two must be laid down from one value.
+        const readerToken = mintReaderRendezvous(env);
+        const readerPlist = readerPlistPath(env);
+        writeFileSync(readerPlist, renderReaderPlist(readerInstalledAppPath(env), readerSocketPath(env), readerToken), { mode: 0o600 });
+        chmodSync(readerPlist, 0o600);
         const readerBoot = launchctl(["bootstrap", `gui/${process.getuid?.() ?? 501}`, readerPlist]);
         if (!readerBoot.ok) {
             warnings.push(`reader launchctl bootstrap failed: ${readerBoot.output.trim()}`);
@@ -258,7 +356,7 @@ export function installHelpers(options = {}, env = process.env) {
         }
     }
     else {
-        warnings.push("the bundle was built without things-reader (no Apple-issued signing identity?) — file reads run direct. Build with an Apple-chain identity, reinstall, then run `things helpers grant`.");
+        warnings.push("the bundle was built without things-reader (no Apple-issued signing identity?) — file reads run direct. Build with an Apple-chain identity, reinstall, then run `things helpers setup`.");
     }
     return {
         bundlePath,
@@ -270,12 +368,116 @@ export function installHelpers(options = {}, env = process.env) {
         warnings,
     };
 }
-/** Stop both halves and remove LaunchAgents + the installed bundle (state — tokens, logs, the reader's grant — is kept). */
-export function uninstallHelpers(env = process.env) {
+/**
+ * The LaunchServices registration tool. `tccutil` addresses grants by BUNDLE
+ * IDENTIFIER and resolves that identifier through LaunchServices, so on a
+ * machine where the bundle is already gone it refuses with -10814 and the
+ * dormant grant rows stay put. Handing LaunchServices the PACKAGED bundle
+ * (`lsregister -f -R "<bundle>"`) makes both identities — the helper and the
+ * reader nested inside it — resolvable again, after which the resets succeed.
+ * Measured on a live host, 2026-08-24.
+ */
+const LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+function runToolDefault(bin, args) {
+    try {
+        const output = execFileSync(bin, args, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 30_000,
+        });
+        return { ok: true, output };
+    }
+    catch (err) {
+        const e = err;
+        return { ok: false, output: `${e.stdout ?? ""}${e.stderr ?? ""}` || (e.message ?? "failed") };
+    }
+}
+/**
+ * Revoke both helper identities' TCC grants (`tccutil reset All` per bundle
+ * identity — Automation, Accessibility, and every other class keyed to them).
+ *
+ * Called BEFORE anything is torn down, because `tccutil` resolves the
+ * identifier through LaunchServices and refuses with -10814
+ * (kLSApplicationNotFoundErr) once no app on disk carries it. When the
+ * installed bundle is already gone, the packaged one is registered first
+ * ({@link LSREGISTER}) and left registered — the file legitimately exists, so
+ * un-registering it would be a lie about the machine. With no bundle anywhere
+ * the resets still run (LaunchServices may hold an older registration) and a
+ * -10814 is reported as the honest limit it is.
+ */
+function revokeGrants(env, deps, warnings) {
+    const runTool = deps.runTool ?? runToolDefault;
+    const packagedBundlePath = deps.packagedBundlePath ?? helpersDefaultBuildPath;
+    let resolvedVia = "installed";
+    let registeredBundle = null;
+    if (!existsSync(deputyInstalledBinaryPath(env))) {
+        const packaged = packagedBundlePath();
+        if (packaged === null) {
+            resolvedVia = "none";
+        }
+        else {
+            const res = runTool(LSREGISTER, ["-f", "-R", packaged]);
+            if (res.ok) {
+                resolvedVia = "packaged";
+                registeredBundle = packaged;
+            }
+            else {
+                resolvedVia = "none";
+                warnings.push(`could not register ${packaged} with LaunchServices: ${res.output.trim() || "unknown"}`);
+            }
+        }
+    }
+    const tccResets = [];
+    for (const target of [HELPERS_BUNDLE_ID, READER_LAUNCHD_LABEL]) {
+        const res = runTool("/usr/bin/tccutil", ["reset", "All", target]);
+        const noApp = !res.ok && /No such bundle identifier|-10814/.test(res.output);
+        tccResets.push({
+            target,
+            ok: res.ok || noApp,
+            detail: res.ok
+                ? res.output.trim() || "reset"
+                : noApp
+                    ? resolvedVia === "none"
+                        ? "no app carries this identifier and none is packaged here — reinstall the helpers, or clear the grants in System Settings ▸ Privacy & Security"
+                        : "no app registered under this identifier — nothing to revoke"
+                    : res.output.trim() || "failed",
+        });
+        if (!res.ok && !noApp) {
+            warnings.push(`tccutil reset All ${target} failed: ${res.output.trim() || "unknown"}`);
+        }
+    }
+    return {
+        tccResets,
+        resolvedVia,
+        registeredBundle,
+        shortcutsNote: "the bundled things-proxy-* shortcuts cannot be removed by any tool — delete them by hand in Shortcuts.app if a truly fresh machine is wanted (`things setup` re-imports them)",
+    };
+}
+/**
+ * Stop both halves and remove their LaunchAgents + the installed bundle.
+ *
+ * By default the macOS grants and the local state (tokens, logs, the reader's
+ * bookmark) are KEPT: the TCC rows are keyed to the two signing identities and
+ * simply go dormant, so a later reinstall picks them straight back up with no
+ * second ceremony. `revoke` turns this into the ceremony's full inverse —
+ * grants revoked first (see {@link revokeGrants}), then the uninstall, then the
+ * reader's container and the deputy's state dir deleted (the read grant is a
+ * bookmark FILE, not a TCC row, so revoking it means deleting it).
+ *
+ * Every leg is independent and IDEMPOTENT: an already-uninstalled helper, an
+ * empty permission store, and absent directories are all fine — each leg does
+ * whatever is still outstanding, so this works from any partial state and a
+ * second run is an all-no-op.
+ */
+export function uninstallHelpers(options = {}, env = process.env, deps = {}) {
+    const warnings = [];
+    const revoke = options.revoke === true;
+    // Revocation runs while the installed bundle (if any) still resolves.
+    const revocation = revoke ? revokeGrants(env, deps, warnings) : null;
     const removed = [];
     launchctl(["bootout", launchTarget()]);
     launchctl(["bootout", readerLaunchTarget()]);
-    for (const path of [deputyPlistPath(), readerPlistPath()]) {
+    for (const path of [deputyPlistPath(env), readerPlistPath(env)]) {
         if (existsSync(path)) {
             rmSync(path);
             removed.push(path);
@@ -286,13 +488,32 @@ export function uninstallHelpers(env = process.env) {
         rmSync(installDir, { recursive: true });
         removed.push(installDir);
     }
-    return { removed };
+    if (revoke) {
+        // The reader's container holds the bookmark that IS the read grant; the
+        // rendezvous holds the access token; the deputy's state dir holds its own.
+        for (const dir of [
+            readerSandboxContainerDir(env),
+            readerRendezvousDir(env),
+            deputyStateDir(env),
+        ]) {
+            if (existsSync(dir)) {
+                try {
+                    rmSync(dir, { recursive: true, force: true });
+                    removed.push(dir);
+                }
+                catch (err) {
+                    warnings.push(`could not remove ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
+    return { removed, revocation, warnings };
 }
 /** Restart the launchd-managed helpers (picks up a rebuilt installed bundle). */
 export function restartHelpers() {
     const res = launchctl(["kickstart", "-k", launchTarget()]);
     if (!res.ok) {
-        throw new Error(`launchctl kickstart failed (${res.output.trim() || "unknown"}) — are the helpers installed? Run: things helpers install`);
+        throw new Error(`launchctl kickstart failed (${res.output.trim() || "unknown"}) — are the helpers installed? Run: things helpers setup`);
     }
     // Reader restart is best-effort: it may legitimately not be installed.
     launchctl(["kickstart", "-k", readerLaunchTarget()]);
@@ -311,7 +532,7 @@ export function grantReader(env = process.env) {
     if (!existsSync(appPath)) {
         return {
             granted: false,
-            detail: "things-reader is not installed — run `things helpers install` first",
+            detail: "things-reader is not installed — run `things helpers setup` first",
         };
     }
     const thingsContainer = join(homedir(), THINGS_GROUP_CONTAINER);
@@ -336,8 +557,8 @@ export function grantReader(env = process.env) {
     const deadline = Date.now() + 15_000;
     let detail = "the reader is not running — `things helpers status`";
     while (Date.now() < deadline) {
-        if (existsSync(socketPath) && existsSync(tokenPath)) {
-            const token = readFileSync(tokenPath, "utf8").trim();
+        const token = rendezvousExists(socketPath) ? readRendezvousToken(tokenPath) : null;
+        if (token !== null) {
             const bridge = new DeputySyncBridge(socketPath);
             try {
                 const res = bridge.request({ v: DEPUTY_PROTOCOL_VERSION, token, verb: "hello" }, 2000);
@@ -348,10 +569,10 @@ export function grantReader(env = process.env) {
                         return { granted: true, detail: "granted" };
                     return {
                         granted: false,
-                        detail: "the grant landed, but the Things database was not found inside the granted folder — rerun `things helpers grant` and grant the Things data folder",
+                        detail: "the grant landed, but the Things database was not found inside the granted folder — rerun `things helpers setup` and grant the Things data folder",
                     };
                 }
-                detail = "the panel closed but no grant landed (canceled?) — rerun `things helpers grant`";
+                detail = "the panel closed but no grant landed (canceled?) — rerun `things helpers setup`";
             }
             catch {
                 detail = "the reader socket is not answering — `things helpers status`";
@@ -367,6 +588,552 @@ export function grantReader(env = process.env) {
 function syncSleepMs(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
+// ---------------------------------------------------------------------------
+// The onboarding ceremony (docs/design/helpers-onboarding.md)
+// ---------------------------------------------------------------------------
+/** How long a consent dialog may stay unanswered before the leg is left pending. */
+const AUTOMATION_PROMPT_TIMEOUT_MS = 120_000;
+/** How long the Accessibility toggle is waited for, and how often it is re-read. */
+const AX_WAIT_TIMEOUT_MS = 120_000;
+const AX_POLL_INTERVAL_MS = 2000;
+/** The deputy kills its child at timeoutMs; the client deadline adds grace. */
+const CLIENT_GRACE_MS = 5000;
+/**
+ * How long the ceremony waits for the deputy's socket. `setup` installs first,
+ * which boots the launchd jobs out and back in, so the socket is legitimately
+ * absent for a moment when the ceremony opens its channel.
+ */
+const DEPUTY_SOCKET_WAIT_MS = 15_000;
+const AX_SETTINGS_URL = "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility";
+/** Which tier each leg belongs to. */
+const LEG_TIER = {
+    "reader-read-grant": "base",
+    "automation-things": "base",
+    "automation-system-events": "gui",
+    accessibility: "gui",
+    shortcuts: "base",
+};
+/** A live sync bridge to the deputy socket, independent of the routing config. */
+function openDeputyChannel(env, waitMs) {
+    const socketPath = deputySocketPath(env);
+    const tokenPath = deputyTokenPath(env);
+    const up = () => existsSync(socketPath) && existsSync(tokenPath);
+    const deadline = Date.now() + waitMs;
+    while (!up() && Date.now() < deadline)
+        syncSleepMs(250);
+    if (!up()) {
+        throw new Error(`the deputy is not running (no socket at ${socketPath}) — \`things helpers status\` to inspect`);
+    }
+    const token = readFileSync(tokenPath, "utf8").trim();
+    const bridge = new DeputySyncBridge(socketPath);
+    const request = (fields, timeoutMs) => {
+        const res = bridge.request({ v: DEPUTY_PROTOCOL_VERSION, token, ...fields }, timeoutMs);
+        if (res["ok"] === true)
+            return res;
+        const err = res["error"];
+        throw new DeputyRequestError(err?.code ?? "internal", err?.message ?? "the deputy refused");
+    };
+    return {
+        hello: () => request({ verb: "hello" }, 5000),
+        request,
+        close: () => {
+            bridge.close();
+        },
+    };
+}
+/** Reader handshake + a `locate` inside the granted scope, on one connection. */
+function readerProbeDefault(env) {
+    const socketPath = readerSocketPath(env);
+    const tokenPath = readerTokenPath(env);
+    if (!rendezvousExists(socketPath) || !rendezvousExists(tokenPath))
+        return null;
+    const token = readRendezvousToken(tokenPath);
+    if (token === null)
+        return null;
+    const bridge = new DeputySyncBridge(socketPath);
+    try {
+        const res = bridge.request({ v: DEPUTY_PROTOCOL_VERSION, token, verb: "hello" }, 2000);
+        if (res["ok"] !== true)
+            return null;
+        const granted = res.granted === true;
+        if (!granted)
+            return { granted: false, locates: false };
+        const locate = bridge.request({ v: DEPUTY_PROTOCOL_VERSION, token, verb: "locate" }, 5000);
+        return { granted: true, locates: locate["ok"] === true };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        bridge.close();
+    }
+}
+function firstLine(text) {
+    return text.trim().split("\n")[0]?.trim() ?? "";
+}
+/**
+ * Both ways out of a denial, always named together. macOS will not show the
+ * Automation dialog again once it has been refused, so the choices are the
+ * System Settings switch or re-arming the dialog by clearing the recorded
+ * refusal. The ceremony NEVER clears a denial itself — that is the user's call.
+ */
+function deniedRemediation(settingsName) {
+    return (`turn on Things API Helper under System Settings ▸ Privacy & Security ▸ Automation ▸ ${settingsName}, ` +
+        `or re-arm the dialog with \`tccutil reset AppleEvents ${HELPERS_BUNDLE_ID}\`, then rerun \`things helpers setup\``);
+}
+/**
+ * One Automation leg: skipped when the deputy already reports the target
+ * granted, otherwise a benign AppleEvent sent THROUGH the deputy — the request
+ * blocks while the consent dialog is up, so answering it right there is what
+ * completes the leg. The event auto-launches its target, which is intended:
+ * macOS has no consent record to hand out while the target is down.
+ *
+ * The probe script MUST dispatch a real Apple event. A handful of
+ * application-object properties (`version`, `name`, `id`, `running`) are
+ * answered locally by the AppleScript runtime from the target's bundle —
+ * no event leaves the process, so no consent dialog is raised and no grant
+ * is minted, while the script still exits 0. That exact false positive
+ * shipped in the first ceremony (probe was `version`; the "granted" leg had
+ * granted nothing), which is also why a 0 exit alone is no longer believed:
+ * the leg re-reads the deputy's own AEDeterminePermission verdict afterwards
+ * and only reports what macOS reports. An old deputy whose hello carries no
+ * automation fields cannot be re-read — there the 0 exit stands, best effort.
+ */
+function automationLeg(channel, spec, known, recheck, timeoutMs, progress) {
+    const base = { leg: spec.leg, label: spec.label, tier: LEG_TIER[spec.leg] };
+    if (known === "granted") {
+        progress(`${spec.label}: already granted`);
+        return { ...base, state: "granted", alreadyGranted: true, detail: "already granted" };
+    }
+    if (known === "denied") {
+        progress(`${spec.label}: denied — the dialog cannot be raised again`);
+        return {
+            ...base,
+            state: "denied",
+            alreadyGranted: false,
+            detail: deniedRemediation(spec.settingsName),
+        };
+    }
+    progress(`${spec.label}: asking now — answer the dialog if one appears`);
+    let res;
+    try {
+        res = channel.request({ verb: "osascript", script: spec.script, lang: "applescript", timeoutMs }, timeoutMs + CLIENT_GRACE_MS);
+    }
+    catch (err) {
+        const why = err instanceof Error ? err.message : String(err);
+        progress(`${spec.label}: no answer (${why})`);
+        return { ...base, state: "pending", alreadyGranted: false, detail: why };
+    }
+    if (res.timedOut === true) {
+        progress(`${spec.label}: still waiting on the dialog`);
+        return {
+            ...base,
+            state: "pending",
+            alreadyGranted: false,
+            detail: `no answer within ${Math.round(timeoutMs / 1000)}s — answer the dialog, then rerun`,
+        };
+    }
+    if (res.exitCode === 0) {
+        const after = recheck();
+        if (after === undefined || after === "granted") {
+            progress(`${spec.label}: granted`);
+            return { ...base, state: "granted", alreadyGranted: false, detail: "granted" };
+        }
+        progress(`${spec.label}: the probe ran but macOS reports no grant (${after})`);
+        return {
+            ...base,
+            state: "pending",
+            alreadyGranted: false,
+            detail: `probe succeeded yet AEDeterminePermission reports "${after}" — rerun, or turn on Things API Helper under System Settings ▸ Privacy & Security ▸ Automation ▸ ${spec.settingsName}`,
+        };
+    }
+    if (res.stderr.includes("-1743")) {
+        progress(`${spec.label}: denied`);
+        return {
+            ...base,
+            state: "denied",
+            alreadyGranted: false,
+            detail: deniedRemediation(spec.settingsName),
+        };
+    }
+    const why = firstLine(res.stderr) || `exit ${res.exitCode}`;
+    progress(`${spec.label}: no grant yet (${why})`);
+    return { ...base, state: "pending", alreadyGranted: false, detail: why };
+}
+/**
+ * The Accessibility leg. Unlike Automation, the grant is not a dialog answer
+ * but a switch in System Settings, so the prompt is fire-and-forget and the
+ * ceremony polls the deputy's own trust bit until it flips.
+ */
+function accessibilityLeg(channel, axTrusted, deps) {
+    const base = { leg: "accessibility", label: "accessibility", tier: "gui" };
+    if (axTrusted === true) {
+        deps.progress("accessibility: already granted");
+        return { ...base, state: "granted", alreadyGranted: true, detail: "already granted" };
+    }
+    try {
+        const res = channel.request({ verb: "prime-ax" }, 10_000);
+        if (res["axTrusted"] === true) {
+            deps.progress("accessibility: already granted");
+            return { ...base, state: "granted", alreadyGranted: true, detail: "already granted" };
+        }
+    }
+    catch (err) {
+        const why = err instanceof Error ? err.message : String(err);
+        deps.progress(`accessibility: could not raise the prompt (${why})`);
+        return { ...base, state: "pending", alreadyGranted: false, detail: why };
+    }
+    deps.progress('accessibility: System Settings ▸ Privacy & Security ▸ Accessibility — turn on "Things API Helper"');
+    deps.openUrl(AX_SETTINGS_URL);
+    deps.progress("accessibility: waiting for the toggle — Ctrl-C and rerun anytime");
+    const deadline = deps.now() + deps.timeoutMs;
+    while (deps.now() < deadline) {
+        deps.sleep(deps.intervalMs);
+        try {
+            if (channel.hello().axTrusted === true) {
+                deps.progress("accessibility: granted");
+                return { ...base, state: "granted", alreadyGranted: false, detail: "granted" };
+            }
+        }
+        catch {
+            // A restart mid-wait (or a momentary hiccup) is not an answer — keep
+            // asking until the deadline; the state is whatever the last read said.
+        }
+    }
+    deps.progress("accessibility: not toggled yet");
+    return {
+        ...base,
+        state: "pending",
+        alreadyGranted: false,
+        detail: `still off after ${Math.round(deps.timeoutMs / 1000)}s — turn on "Things API Helper" under System Settings ▸ Privacy & Security ▸ Accessibility, then rerun`,
+    };
+}
+/** The bundled proxy shortcuts, counted through the deputy's `shortcuts list`. */
+function shortcutsLeg(channel, progress) {
+    const base = { leg: "shortcuts", label: "shortcuts", tier: "base" };
+    let installed;
+    try {
+        const res = channel.request({ verb: "shortcuts", op: "list", timeoutMs: 20_000 }, 20_000 + CLIENT_GRACE_MS);
+        if (res.exitCode !== 0 || res.timedOut === true) {
+            const why = firstLine(res.stderr) || `exit ${res.exitCode}`;
+            progress(`shortcuts: could not list them (${why})`);
+            return { ...base, state: "pending", alreadyGranted: false, detail: why };
+        }
+        installed = new Set(res.stdout
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line !== ""));
+    }
+    catch (err) {
+        const why = err instanceof Error ? err.message : String(err);
+        progress(`shortcuts: could not list them (${why})`);
+        return { ...base, state: "pending", alreadyGranted: false, detail: why };
+    }
+    const missing = EXPECTED_PROXIES.filter((name) => !installed.has(name));
+    if (missing.length === 0) {
+        progress(`shortcuts: all ${EXPECTED_PROXIES.length} installed`);
+        return {
+            ...base,
+            state: "granted",
+            alreadyGranted: true,
+            detail: `all ${EXPECTED_PROXIES.length} installed`,
+        };
+    }
+    progress(`shortcuts: ${missing.length} missing — run \`things setup\``);
+    return {
+        ...base,
+        state: "skipped-not-installed",
+        alreadyGranted: false,
+        detail: `missing ${missing.join(", ")} — run \`things setup\` (it opens the import screen for each)`,
+    };
+}
+function readerStanding(env, readerProbe) {
+    if (!existsSync(readerInstalledAppPath(env)))
+        return "not-installed";
+    const probe = readerProbe();
+    return probe !== null && probe.granted && probe.locates ? "granted" : "needs-panel";
+}
+/** The reader's durable read grant — skipped when a database already resolves inside it. */
+function readerLeg(standing, deps) {
+    const base = {
+        leg: "reader-read-grant",
+        label: "reader read grant",
+        tier: "base",
+    };
+    if (standing === "not-installed") {
+        deps.progress("reader read grant: the reader is not part of the installed bundle");
+        return {
+            ...base,
+            state: "skipped-not-installed",
+            alreadyGranted: false,
+            detail: "the bundle was built without things-reader (no Apple-issued signing identity) — database reads run direct",
+        };
+    }
+    if (standing === "granted") {
+        deps.progress("reader read grant: already granted");
+        return { ...base, state: "granted", alreadyGranted: true, detail: "already granted" };
+    }
+    deps.progress("reader read grant: accept the folder panel the reader is opening");
+    const result = deps.grant();
+    if (result.granted) {
+        deps.progress("reader read grant: granted");
+        return { ...base, state: "granted", alreadyGranted: false, detail: "granted" };
+    }
+    deps.progress(`reader read grant: not granted (${result.detail})`);
+    return { ...base, state: "pending", alreadyGranted: false, detail: result.detail };
+}
+/**
+ * The hint the BASE tier closes with (Article V, tiered). A machine that never
+ * asked for GUI-driving should still learn that the capability exists and what
+ * it buys, exactly once, at the moment it has just finished setting up.
+ */
+const GUI_TIER_HINT = "GUI-driving is not set up — some features drive the app window (repeat-rule edits, area " +
+    "reorder); run `things helpers setup --gui` to enable.";
+function closingLine(steps, mode, tier) {
+    const denied = steps.filter((s) => s.state === "denied");
+    if (denied.length > 0) {
+        return (`setup did not finish — ${denied.map((s) => s.label).join(" and ")} ${denied.length === 1 ? "is" : "are"} denied. ` +
+            `Turn Things API Helper on under System Settings ▸ Privacy & Security ▸ Automation, or re-arm the dialog with ` +
+            `\`tccutil reset AppleEvents ${HELPERS_BUNDLE_ID}\`, then rerun \`things helpers setup\`.`);
+    }
+    const pending = steps.filter((s) => s.state === "pending");
+    if (pending.length > 0) {
+        return (`setup did not finish — ${pending.map((s) => s.label).join(", ")} still needs you. ` +
+            `Rerun \`things helpers setup\` to resume exactly there; everything already granted is skipped.`);
+    }
+    const shortcutsMissing = steps.some((s) => s.leg === "shortcuts" && s.state === "skipped-not-installed");
+    const guiHint = tier === "base" ? ` ${GUI_TIER_HINT}` : "";
+    if (mode === "false") {
+        return ("everything asked for is granted, but routing is off — `things config set helpers-enabled auto` " +
+            `to send reads and writes through the helpers.${guiHint}`);
+    }
+    const base = "you're done — writes and reads route through the helpers with no further prompts.";
+    const shortcuts = shortcutsMissing
+        ? " The bundled shortcuts are still missing; run `things setup` if you want that path too."
+        : "";
+    return `${base}${shortcuts}${guiHint}`;
+}
+/** What each leg puts on screen, for the upfront banner. */
+const PROMPT_LABELS = {
+    "reader-read-grant": "the reader's folder panel",
+    "automation-things": "app control for Things",
+    "automation-system-events": "app control for System Events",
+    accessibility: "the Accessibility switch",
+    // The census asks the deputy, never the user.
+    shortcuts: "",
+};
+/**
+ * What the human is about to see, in the words macOS will actually use. The
+ * wizard prints these one leg ahead of the dialog (Article V, mode-aware); in
+ * strict mode they are never printed and the upfront banner's count stands
+ * alone.
+ */
+const PROMPT_EXPLAINERS = {
+    "reader-read-grant": [
+        "Next: read access to your Things data.",
+        "  A file panel opens, already inside the Things data folder — click Grant Access.",
+        "  Nothing else in that panel needs changing; do not navigate elsewhere.",
+    ],
+    "automation-things": [
+        "Next: permission for the helper to control Things.",
+        '  A macOS dialog will appear: "Things API Helper" wants access to control "Things" —',
+        "  click Allow. Things opens if it was closed; that is expected.",
+    ],
+    "automation-system-events": [
+        "Next: permission for the helper to control System Events (the GUI-driving tier).",
+        '  A macOS dialog will appear: "Things API Helper" wants access to control',
+        '  "System Events" — click Allow. System Events is the macOS component that reads and',
+        "  presses the Things window's own controls.",
+    ],
+    accessibility: [
+        "Next: the Accessibility switch (the GUI-driving tier).",
+        "  System Settings opens at Privacy & Security ▸ Accessibility — turn on",
+        '  "Things API Helper" in that list. This one is a switch you flip, not a dialog you',
+        "  answer, so setup waits and watches for it.",
+    ],
+    shortcuts: [],
+};
+/**
+ * Which legs are about to put something on screen, surveyed prompt-free from
+ * the deputy's handshake and the reader's bookmark state. A leg macOS already
+ * records as `denied` raises nothing (the dialog is spent), so it is not
+ * counted here even though it will be reported as a failure.
+ */
+function willRaiseAutomationDialog(state) {
+    return state !== "granted" && state !== "denied";
+}
+function outstandingPrompts(hello, reader, tier) {
+    const outstanding = [];
+    if (reader === "needs-panel")
+        outstanding.push("reader-read-grant");
+    if (willRaiseAutomationDialog(hello.automation?.things))
+        outstanding.push("automation-things");
+    if (tier === "gui") {
+        if (willRaiseAutomationDialog(hello.automation?.systemEvents)) {
+            outstanding.push("automation-system-events");
+        }
+        if (hello.axTrusted !== true)
+            outstanding.push("accessibility");
+    }
+    return outstanding;
+}
+/** The interactive tier question, asked only when nothing else decided it. */
+const GUI_TIER_QUESTION = "Some Things features have no programmatic surface and are driven through the app's own " +
+    "window (editing repeat rules, reordering areas). Enable GUI-driving permissions?";
+/**
+ * The full onboarding ceremony behind `things helpers setup`: fire every
+ * consent macOS will ever ask for while a human is sitting there, then report
+ * where each one landed. Every leg is IDEMPOTENT — an already-granted leg is
+ * detected prompt-free (the deputy's own `hello` carries its TCC standing) and
+ * skipped — so a rerun on a fully onboarded machine raises nothing and reports
+ * all-green. Interactive by design: run it at the machine.
+ *
+ * Throws when the helpers are not installed or the deputy does not answer;
+ * every other outcome is reported per leg. See docs/design/helpers-onboarding.md.
+ *
+ * Runs under `withDefaultInterrupts` for its whole synchronous span, so Ctrl-C
+ * stops it at a gate AND inside the Accessibility wait (../wizard.ts, "Why a
+ * ceremony runs with the DEFAULT signal disposition"). Throws `CeremonyStopped`
+ * when the human stops at a gate.
+ */
+export function onboardHelpers(options, env = process.env, deps = {}) {
+    return withDefaultInterrupts(() => runOnboardCeremony(options, env, deps));
+}
+function runOnboardCeremony(options, env, deps) {
+    const mode = options.mode;
+    const progress = deps.progress ??
+        ((line) => {
+            process.stdout.write(`${line}\n`);
+        });
+    const wizard = deps.wizard ?? createWizard();
+    if (deps.channel === undefined && !existsSync(deputyInstalledBinaryPath(env))) {
+        throw new Error("the helpers are not installed — run `things helpers setup` first");
+    }
+    // Which tier, decided BEFORE anything is raised so the banner can size the
+    // sitting honestly. The flag wins; `ui-enabled` already on implies the tier
+    // without it (a machine that opted into GUI-driving is asking for the grants
+    // by definition); otherwise a TTY sitting is asked and a strict run is not.
+    const uiEnabled = (deps.uiEnabled ?? (() => loadConfig(env).ui.enabled))();
+    let guiRequestedBy = null;
+    if (options.gui === true) {
+        guiRequestedBy = "flag";
+    }
+    else if (uiEnabled) {
+        guiRequestedBy = "config";
+        progress("ui.enabled is on — including GUI-driving permissions.");
+    }
+    else if (wizard.ask(GUI_TIER_QUESTION, false)) {
+        guiRequestedBy = "wizard";
+    }
+    const tier = guiRequestedBy === null ? "base" : "gui";
+    const channel = deps.channel ?? openDeputyChannel(env, deps.deputyWaitMs ?? DEPUTY_SOCKET_WAIT_MS);
+    const steps = [];
+    let outstanding = [];
+    try {
+        let hello;
+        try {
+            hello = channel.hello();
+        }
+        catch (err) {
+            throw new Error(`the deputy is installed but did not answer (${err instanceof Error ? err.message : String(err)}) — \`things helpers restart\`, then rerun`, { cause: err });
+        }
+        if (hello.deputyVersion !== EXPECTED_HELPERS_VERSION) {
+            progress(`note: the installed helpers are v${hello.deputyVersion}, this package expects v${EXPECTED_HELPERS_VERSION} — rebuild with \`bash scripts/build-helpers.sh\` and rerun \`things helpers setup\` for the full ceremony`);
+        }
+        // Size the sitting BEFORE raising anything, so whoever started this knows
+        // whether they have to stay at the screen.
+        const reader = readerStanding(env, deps.readerProbe ?? (() => readerProbeDefault(env)));
+        outstanding = outstandingPrompts(hello, reader, tier);
+        progress(outstanding.length === 0
+            ? "nothing to raise — every permission the helpers need is already on record"
+            : `about to raise ${outstanding.length} macOS consent dialog${outstanding.length === 1 ? "" : "s"} — ` +
+                `${outstanding.map((leg) => PROMPT_LABELS[leg]).join(", ")}. Someone must be at the screen.`);
+        const willRaise = new Set(outstanding);
+        /** Explain a leg's dialog and let the human pace it — wizard mode only. */
+        const brief = (leg) => {
+            if (willRaise.has(leg))
+                wizard.explain(PROMPT_EXPLAINERS[leg]);
+        };
+        brief("reader-read-grant");
+        steps.push(readerLeg(reader, {
+            progress,
+            grant: deps.grant ?? (() => grantReader(env)),
+        }));
+        const automationTimeoutMs = deps.automationTimeoutMs ?? AUTOMATION_PROMPT_TIMEOUT_MS;
+        // Fresh AEDeterminePermission read for one target, off a new hello.
+        const refreshAutomation = (key) => () => {
+            try {
+                return channel.hello().automation?.[key];
+            }
+            catch {
+                return undefined;
+            }
+        };
+        brief("automation-things");
+        steps.push(automationLeg(channel, {
+            leg: "automation-things",
+            label: "automation → Things",
+            // `count of areas` dispatches a REAL Apple event; `version` and its
+            // kin are answered locally and would grant nothing (see automationLeg).
+            script: 'tell application "Things3" to count of areas',
+            settingsName: "Things3",
+        }, hello.automation?.things, refreshAutomation("things"), automationTimeoutMs, progress));
+        // The GUI tier. Skipped entirely under the base tier — Accessibility and
+        // System Events are the two widest grants the pair ever holds, so they are
+        // gathered only when GUI-driving was actually asked for (Article V).
+        if (tier === "gui") {
+            brief("automation-system-events");
+            steps.push(automationLeg(channel, {
+                leg: "automation-system-events",
+                label: "automation → System Events",
+                script: 'tell application "System Events" to name of first process',
+                settingsName: "System Events",
+            }, hello.automation?.systemEvents, refreshAutomation("systemEvents"), automationTimeoutMs, progress));
+            brief("accessibility");
+            steps.push(accessibilityLeg(channel, hello.axTrusted, {
+                progress,
+                openUrl: deps.openUrl ?? openUrlBestEffort,
+                sleep: deps.sleep ?? syncSleepMs,
+                now: deps.now ?? Date.now,
+                timeoutMs: deps.axTimeoutMs ?? AX_WAIT_TIMEOUT_MS,
+                intervalMs: deps.axIntervalMs ?? AX_POLL_INTERVAL_MS,
+            }));
+        }
+        steps.push(shortcutsLeg(channel, progress));
+    }
+    finally {
+        channel.close();
+    }
+    // A GUI tier that actually landed turns the config key on, so the capability
+    // the user just granted is the capability the engine will use. Only on full
+    // success: switching the key on over a half-granted tier would produce
+    // exactly the "enabled but refuses" state Article IV exists to prevent.
+    const guiGranted = tier === "gui" && steps.every((s) => s.tier !== "gui" || s.state === "granted");
+    let uiEnabledSet = false;
+    if (guiGranted && !uiEnabled) {
+        (deps.setUiEnabled ?? ((value) => saveConfigKey("uiEnabled", value, env)))(true);
+        uiEnabledSet = true;
+        progress("GUI-driving turned on in config (`ui-enabled` is now true).");
+    }
+    return {
+        tier,
+        guiRequestedBy,
+        uiEnabledSet,
+        steps,
+        outstanding,
+        denied: steps.some((s) => s.state === "denied"),
+        pending: steps.some((s) => s.state === "pending"),
+        closing: closingLine(steps, mode, tier),
+    };
+}
+function openUrlBestEffort(url) {
+    try {
+        execFileSync("open", [url], { stdio: "ignore", timeout: 10_000 });
+    }
+    catch {
+        // The deep link is a convenience; the written path works without it.
+    }
+}
 /**
  * Prompt-free status for both halves: launchd load state, a live handshake
  * when each socket answers, and the installed bundle's signing facts. Works
@@ -406,7 +1173,7 @@ export function helpersStatus(mode, env = process.env) {
         bundleInstalled: binaryInstalled,
         installedVersion: installedHelpersVersion(env),
         deputy: {
-            plistInstalled: existsSync(deputyPlistPath()),
+            plistInstalled: existsSync(deputyPlistPath(env)),
             loaded: launchctl(["print", launchTarget()]).ok,
             running: hello !== null,
             socketPath,
@@ -427,10 +1194,15 @@ function readerStatus(env) {
     let running = false;
     let granted = false;
     let hello = null;
-    let detail = "not running (no socket)";
-    const socketPresent = existsSync(socketPath) && existsSync(tokenPath);
-    if (socketPresent) {
-        const token = readFileSync(tokenPath, "utf8").trim();
+    // The rendezvous is `<state>/reader`, ours and outside every sandbox
+    // container, so `helpers status` answers this identically from any host app.
+    let detail = "not registered with launchd (no rendezvous)";
+    const socketPresent = rendezvousExists(socketPath) && rendezvousExists(tokenPath);
+    const token = socketPresent ? readRendezvousToken(tokenPath) : null;
+    if (socketPresent && token === null) {
+        detail = `the reader's access token could not be read (${tokenPath}) — \`things helpers setup\` mints a fresh one`;
+    }
+    if (token !== null) {
         const bridge = new DeputySyncBridge(socketPath);
         try {
             const res = bridge.request({ v: DEPUTY_PROTOCOL_VERSION, token, verb: "hello" }, 2000);
@@ -438,7 +1210,7 @@ function readerStatus(env) {
                 running = true;
                 hello = res;
                 granted = res.granted === true;
-                detail = granted ? "running, granted" : "running, NOT granted (things helpers grant)";
+                detail = granted ? "running, granted" : "running, NOT granted (things helpers setup)";
             }
             else {
                 detail = `handshake refused: ${JSON.stringify(res["error"])}`;
@@ -453,12 +1225,12 @@ function readerStatus(env) {
     }
     return {
         installed,
-        plistInstalled: existsSync(readerPlistPath()),
+        plistInstalled: existsSync(readerPlistPath(env)),
         loaded,
         running,
         granted,
         socketPath,
-        hungSocket: socketPresent && !running,
+        hungSocket: socketPresent && token !== null && !running,
         hello,
         signing: installed ? deputySigningInfo(readerExecPath(appPath)) : null,
         detail,