things-api 0.17.0 → 0.19.0

package/dist/capability.js

@@ -0,0 +1,416 @@
+/**
+ * Prompt-free capability detection (docs/design/permissions-doctrine.md,
+ * Articles I–III).
+ *
+ * Every entry point must know what it is allowed to do BEFORE it touches the
+ * live library, and it must find out without putting a macOS consent dialog on
+ * screen. This module is the single place that answers that question, so the
+ * read gate, the write gate, `things doctor`, and the `things setup` ceremony
+ * all quote the same verdict.
+ *
+ * Read capability is GROUND TRUTH per invocation, never a stored flag. Nothing
+ * here is memoized across calls and nothing is persisted except the one marker
+ * that records a live-instance fact (./session-grant.ts). The whole preflight
+ * is a single `open(2)` in the common case.
+ *
+ * The paths, in the order they are consulted:
+ *
+ *  1. an explicit database path — outside the doctrine entirely (Article VI);
+ *  2. the helpers — when the reader is serving this process's reads, the READ
+ *     ITSELF is the check. The reader resolves its security-scoped bookmark on
+ *     every verb and answers `not-granted` / `not-found` as typed errors, so
+ *     there is nothing to pre-probe and no hello round-trip is added here. When
+ *     the helpers are expected but cannot serve, the read FAILS LOUDLY — a
+ *     silent fall-through to direct would move consent back onto the terminal,
+ *     which is the exact churn the helpers exist to end;
+ *  3. Full Disk Access — one read-open of the user TCC database. FDA-class
+ *     files never raise a dialog: the open either works or fails with a silent
+ *     EPERM;
+ *  4. a witnessed session app-data grant — see ./session-grant.ts;
+ *  5. otherwise: refuse, naming both setup ceremonies.
+ *
+ * Step 2 asks nothing of this host's grants. Since helpers 1.3.0 the reader's
+ * socket and token live in `<state>/reader` — launchd owns the socket, install
+ * mints the token, and both are ordinary files this user owns — so "is the
+ * reader serving?" is answerable identically from every host app, with no
+ * consent class in play. (Before 1.3.0 they sat in the reader's App Sandbox
+ * container and that question was itself a cross-app container access.)
+ *
+ * The Things group container is NEVER opened as a probe (Article I corollary):
+ * the open is itself what raises the app-data consent, so "try it and see" is
+ * forbidden — except inside `things setup`, which provokes it deliberately.
+ *
+ * On the direct WRITE probe — why TCC introspection and not the AppleEvents
+ * API. The doctrine names `AEDeterminePermissionToAutomateTarget(askUserIfNeeded:
+ * false)` as the direct-path Automation probe, which is exactly what the deputy
+ * calls (deputy/src/tcc.swift). From a JXA/ObjC host that call is NOT reachable:
+ * JavaScriptCore's bridge cannot marshal an `AEDesc` struct. MEASURED 2026-08-24
+ * on macOS 24.6 — `AECreateDesc` fills an untyped `Ref()`, but passing that Ref
+ * to any function taking `^{AEDesc=…}` throws "Ref has incompatible type", and
+ * the one spelling the bridge accepts (`ref[0]`, a dereferenced copy) arrives
+ * zeroed: `AEGetDescDataSize` reports 0 bytes for a 36-byte bundle id, and every
+ * target then answers -50 paramErr. A probe that returns the same wrong answer
+ * for every input is worse than no probe, so it is not shipped. Reading the
+ * Automation row out of TCC.db is the other introspection the Article I
+ * corollary names, it is exactly as prompt-free, and it costs nothing extra:
+ * direct mode's floor is FDA anyway, so a process that can act at all can
+ * already read that file. Where the row cannot be read the verdict is an honest
+ * "unknown", which the write gate refuses on rather than resolving with a dialog.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { loadConfig } from "./config.js";
+import { deputyRouting, deputyRoutesDb, helpersExpected } from "./deputy/routing.js";
+import { fdaGranted, hostApp, hostDisplayName, resetHostAccessForTests, tccDbPath, } from "./host-access.js";
+import { sessionGrantValid } from "./session-grant.js";
+export { fdaGranted, hostApp, hostDisplayName, tccDbPath, } from "./host-access.js";
+/** The Things application's bundle identifier — the Automation grant's target. */
+export const THINGS_BUNDLE_ID = "com.culturedcode.ThingsMac";
+/** True when this verdict permits opening the live container. */
+export function readAllowed(capability) {
+    return capability.mode !== "none" && capability.mode !== "helpers-unavailable";
+}
+/** True when this verdict permits driving the Things window. */
+export function uiAllowed(capability) {
+    return capability.mode === "helpers" || capability.mode === "direct-escape";
+}
+/** True when app automation may be dispatched. */
+export function writeAllowed(capability) {
+    return capability.mode === "deputy" || capability.mode === "direct-granted";
+}
+// ── The prompt-free probes ───────────────────────────────────────────────────
+/**
+ * One Automation row from TCC.db: the `auth_value` macOS records for `client`
+ * driving `target`, or null when there is no row (never asked) or the file is
+ * unreadable (no FDA). Read-only, prompt-free, and defensive — the schema is
+ * Apple's private business, so ANY failure degrades to null rather than
+ * throwing into a caller that asked a yes/no question.
+ */
+function automationAuthValueDefault(env, client, target) {
+    let db;
+    try {
+        db = new DatabaseSync(tccDbPath(env), { readOnly: true });
+        const row = db
+            .prepare("SELECT auth_value FROM access WHERE service = 'kTCCServiceAppleEvents' " +
+            "AND client = ? AND indirect_object_identifier = ? LIMIT 1")
+            .get(client, target);
+        const value = row?.auth_value;
+        return typeof value === "number" ? value : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch {
+            // A close failure cannot change the answer we already have.
+        }
+    }
+}
+// ── Read capability (Article I + II) ─────────────────────────────────────────
+/**
+ * Errnos that mean a plain "no" rather than something worth telling the user
+ * about. EPERM is the FDA denial proper; EACCES is its sandboxed cousin; ENOENT
+ * simply means this account has no TCC database yet. Anything else is an
+ * anomaly and gets named, so a genuinely odd failure is never silently folded
+ * into "you lack permission".
+ */
+const ORDINARY_DENIALS = new Set(["EPERM", "EACCES", "ENOENT"]);
+/** The ways a machine can earn read capability, phrased for a human. */
+function readRemediation(hostName) {
+    return [
+        "run `things helpers setup` — reads then flow through a helper that holds its own durable grant",
+        `or grant Full Disk Access to ${hostName} in System Settings ▸ Privacy & Security ▸ Full Disk Access`,
+        "or run `things setup`, which walks through both",
+    ];
+}
+/**
+ * Can this process read the live Things library, and on whose authority?
+ *
+ * Stateless: every call re-derives the verdict, because a grant can appear or
+ * vanish between one invocation and the next and a cached "yes" would be a
+ * stored onboarding flag by another name. The common case costs one `open(2)`.
+ */
+export function readCapability(options = {}, deps = {}) {
+    const env = deps.env ?? process.env;
+    const host = hostApp(deps);
+    // Article VI — a path the caller already owns gets plain file semantics.
+    if (options.dbPath !== undefined || (env["THINGS_DB"] ?? "") !== "") {
+        return {
+            mode: "explicit-db",
+            detail: "an explicit database path was supplied — plain file semantics apply",
+            remediation: [],
+            host,
+        };
+    }
+    // The helpers path. Reads that ride the reader are not pre-checked here: the
+    // reader resolves its bookmark on every verb, so the read IS the check and a
+    // probe would only add latency and a second answer to disagree with.
+    const serving = (deps.helpersServing ?? (() => deputyRoutesDb(options, env)))();
+    if (serving) {
+        return {
+            mode: "helpers",
+            detail: "database reads are served by the sandboxed reader",
+            remediation: [],
+            host,
+        };
+    }
+    // No silent fall-through: a machine that asked for the helpers and cannot
+    // have them is refused, not quietly downgraded onto the terminal's own grants.
+    // Nothing gates this question any more — the rendezvous is ours, so whether
+    // the helpers are expected and whether they are serving are both answerable
+    // from every host app alike.
+    const expected = (deps.helpersExpected ?? (() => helpersExpected(env)))();
+    if (expected) {
+        const why = (deps.helpersReason ?? (() => null))();
+        return {
+            mode: "helpers-unavailable",
+            detail: `the helpers are enabled on this machine but are not serving reads${why !== null ? ` (${why})` : ""}`,
+            remediation: [
+                "run `things helpers setup` to finish onboarding them",
+                "or `things helpers status` to see which half is unhealthy",
+                "or `things --no-helpers …` to run this one invocation directly",
+            ],
+            host,
+        };
+    }
+    const fda = fdaGranted(deps);
+    if (fda.granted) {
+        return {
+            mode: "direct-fda",
+            detail: `Full Disk Access is held by ${hostDisplayName(deps)}${host.bundleId !== null ? ` (${host.bundleId})` : ""}`,
+            remediation: [],
+            host,
+        };
+    }
+    // The sub-FDA tier: a grant a ceremony witnessed, still live for this very
+    // app instance. Only consulted when FDA has already said no.
+    const session = sessionGrantValid(host.bundleId, deps);
+    if (session.valid) {
+        return {
+            mode: "session-grant",
+            detail: `${hostDisplayName(deps)} was granted access to the Things data folder for as long as it stays open`,
+            remediation: [],
+            host,
+        };
+    }
+    return {
+        mode: "none",
+        detail: `${hostDisplayName(deps)} cannot open the Things data folder — ${session.reason}` +
+            (fda.code !== null && !ORDINARY_DENIALS.has(fda.code)
+                ? ` (the access check ended in ${fda.code})`
+                : ""),
+        remediation: readRemediation(hostDisplayName(deps)),
+        host,
+    };
+}
+/** Thrown when a read is refused for want of capability (Article II). */
+export class ReadCapabilityError extends Error {
+    remediation;
+    capability;
+    constructor(capability) {
+        super(`the Things database cannot be read: ${capability.detail}. ` +
+            `${capability.remediation.join("; ")}.`);
+        this.name = "ReadCapabilityError";
+        this.remediation = capability.remediation;
+        this.capability = capability;
+    }
+}
+// ── Write capability (Article I + II) ────────────────────────────────────────
+/**
+ * macOS `auth_value` for an Automation record. 0 is a refusal; 2 (allowed) and
+ * 3 both mean the event will be delivered.
+ */
+function classifyAuthValue(value) {
+    if (value === null)
+        return "unknown";
+    if (value === 0)
+        return "denied";
+    if (value >= 2)
+        return "granted";
+    return "unknown";
+}
+/**
+ * May this process drive Things over Apple Events, and on whose authority?
+ *
+ * The deputy wins when it is onboarded (its own handshake reports the grant it
+ * holds). Otherwise the host app's own Automation record is read out of TCC —
+ * granted, denied, or, when there is no record at all, `direct-unknown`. That
+ * last state is deliberately NOT resolved here: resolving it means sending a
+ * real Apple Event, which is what raises the dialog, and Article I reserves
+ * that for `things setup`.
+ */
+export function writeCapability(deps = {}) {
+    const env = deps.env ?? process.env;
+    const host = hostApp(deps);
+    const deputyThings = (deps.deputyAutomation ?? (() => deputyRouting(env).hello?.automation?.things))();
+    if (deputyThings === "granted") {
+        return {
+            mode: "deputy",
+            detail: "the deputy is onboarded and holds app control for Things",
+            remediation: [],
+            host,
+        };
+    }
+    if (host.bundleId === null) {
+        return {
+            mode: "direct-unknown",
+            detail: "this process does not descend from an application bundle, so macOS has no identity " +
+                "to record app control against",
+            remediation: [
+                "run `things helpers setup` — app control then attaches to a helper that always has an identity",
+            ],
+            host,
+        };
+    }
+    const authValue = (deps.automationAuthValue ??
+        ((client, target) => automationAuthValueDefault(env, client, target)))(host.bundleId, THINGS_BUNDLE_ID);
+    const hostName = hostDisplayName(deps);
+    switch (classifyAuthValue(authValue)) {
+        case "granted":
+            return {
+                mode: "direct-granted",
+                detail: `${hostName} (${host.bundleId}) holds app control for Things`,
+                remediation: [],
+                host,
+            };
+        case "denied":
+            return {
+                mode: "direct-denied",
+                detail: `macOS records a refusal of app control for ${hostName} (${host.bundleId}) — it will not ask again`,
+                remediation: [
+                    `turn on Things3 for ${hostName} under System Settings ▸ Privacy & Security ▸ Automation`,
+                    `or re-arm the request with \`tccutil reset AppleEvents ${host.bundleId}\`, then run \`things setup\``,
+                ],
+                host,
+            };
+        default:
+            return {
+                mode: "direct-unknown",
+                detail: `macOS has no app-control record for ${hostName} (${host.bundleId}) yet`,
+                remediation: [
+                    "run `things setup` — it asks for app control once, while you are at the machine",
+                    "or run `things helpers setup` to attach the grant to a helper instead",
+                ],
+                host,
+            };
+    }
+}
+/** Thrown when app automation is refused for want of capability (Article II). */
+export class WriteCapabilityError extends Error {
+    remediation;
+    capability;
+    constructor(capability) {
+        super(`Things cannot be driven: ${capability.detail}. ${capability.remediation.join("; ")}.`);
+        this.name = "WriteCapabilityError";
+        this.remediation = capability.remediation;
+        this.capability = capability;
+    }
+}
+// ── UI capability (Article IV) ───────────────────────────────────────────────
+/**
+ * The LAB's escape hatch, and deliberately not consumer surface. The VM lab and
+ * the guest e2e bundle drive the UI vector DIRECT — the in-guest Accessibility
+ * grant is held by the runner's own processes (the AXVM1 layer), there is no
+ * helper bundle in a disposable clone, and there is nobody to answer a dialog
+ * either. Setting this to `1` restores direct UI-vector availability for that
+ * one situation. It is documented in docs/lab/harness.md and exported by the
+ * lab's guest environment; nothing consumer-facing mentions it, and it does not
+ * bypass `ui.enabled` — a lab clone still sets that key explicitly.
+ */
+export const UI_DIRECT_ESCAPE_ENV = "THINGS_API_UI_DIRECT";
+/** The command that gathers the GUI-driving tier, named in every UI refusal. */
+const GUI_SETUP_COMMAND = "run `things helpers setup --gui` to grant GUI-driving to the helpers";
+function deputyGuiStandingDefault(env) {
+    const hello = deputyRouting(env).hello;
+    if (hello === undefined || hello === null)
+        return null;
+    return { axTrusted: hello.axTrusted, systemEvents: hello.automation?.systemEvents };
+}
+/**
+ * May this process drive the Things WINDOW, and on whose authority?
+ *
+ * Article IV admits exactly one provenance: the helper pair. Accessibility on a
+ * general-purpose host app (a terminal, an agent harness, an MCP host) has a
+ * blast radius far beyond Things, churns with every host update, and has no
+ * sane story at all over ssh — so direct AX is unsupported, and a refusal here
+ * names the config knob and `things helpers setup --gui` rather than raising an
+ * Accessibility prompt against whatever happens to be running us.
+ *
+ * Every answer is prompt-free: the config key is a file read, and the deputy's
+ * `hello` carries `AXIsProcessTrusted()` plus its own `AEDeterminePermission`
+ * verdict for System Events.
+ */
+export function uiCapability(deps = {}) {
+    const env = deps.env ?? process.env;
+    const host = hostApp(deps);
+    const enabled = (deps.uiEnabled ?? (() => loadConfig(env).ui.enabled))();
+    if (!enabled) {
+        return {
+            mode: "config-disabled",
+            detail: "GUI-driving is switched off on this machine (`ui-enabled` is false)",
+            remediation: [
+                "run `things config set ui-enabled true` to opt in",
+                `then ${GUI_SETUP_COMMAND}`,
+            ],
+            host,
+        };
+    }
+    if ((env[UI_DIRECT_ESCAPE_ENV] ?? "") === "1") {
+        return {
+            mode: "direct-escape",
+            detail: `${UI_DIRECT_ESCAPE_ENV}=1 — GUI-driving runs directly under this process (lab escape)`,
+            remediation: [],
+            host,
+        };
+    }
+    const standing = (deps.deputyGuiStanding ?? (() => deputyGuiStandingDefault(env)))();
+    if (standing === null) {
+        return {
+            mode: "helpers-missing",
+            detail: "GUI-driving is granted only to the helpers, and no helper is answering on this machine",
+            remediation: [GUI_SETUP_COMMAND, "or `things helpers status` to see which half is unhealthy"],
+            host,
+        };
+    }
+    const missing = [];
+    if (standing.axTrusted !== true) {
+        missing.push(standing.axTrusted === undefined
+            ? "Accessibility (these helpers predate the permission handshake — rebuild)"
+            : "Accessibility");
+    }
+    if (standing.systemEvents !== "granted") {
+        missing.push(`automation → System Events (${standing.systemEvents ?? "unknown"})`);
+    }
+    if (missing.length === 0) {
+        return {
+            mode: "helpers",
+            detail: "the helpers hold Accessibility and app control for System Events",
+            remediation: [],
+            host,
+        };
+    }
+    return {
+        mode: "tier-incomplete",
+        detail: `the helpers are onboarded but the GUI-driving tier is incomplete — missing ${missing.join("; ")}`,
+        remediation: [GUI_SETUP_COMMAND],
+        host,
+    };
+}
+/** Thrown when GUI-driving is refused for want of capability (Article IV). */
+export class UiCapabilityError extends Error {
+    remediation;
+    capability;
+    constructor(capability) {
+        super(`the Things window cannot be driven: ${capability.detail}. ${capability.remediation.join("; ")}.`);
+        this.name = "UiCapabilityError";
+        this.remediation = capability.remediation;
+        this.capability = capability;
+    }
+}
+/** Test seam: forget the one memo this module keeps (the host's display name). */
+export function resetCapabilityForTests() {
+    resetHostAccessForTests();
+}
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

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

package/dist/cli/commands/doctor.js

@@ -1,6 +1,121 @@
 import { describeEnvironmentChanges, diagnose, errorEnvelope, okEnvelope, } from "../../index.js";
 // Back-compat alias for pre-seam consumers of the CLI module.
 export const runDoctor = diagnose;
+/**
+ * What this process may do and who holds the grant that lets it
+ * (docs/design/permissions-doctrine.md, Article II). Two lines, always first:
+ * every other row below is downstream of these two answers.
+ */
+function capabilityLines(capability) {
+    const { read, write } = capability;
+    const host = read.host.bundleId !== null ? `${read.host.name} (${read.host.bundleId})` : read.host.name;
+    const lines = [
+        `host app:    ${host}`,
+        `read access: ${read.mode} — ${read.detail}`,
+        `app control: ${write.mode} — ${write.detail}`,
+    ];
+    for (const line of [...read.remediation, ...write.remediation]) {
+        lines.push(`  next:      ${line}`);
+    }
+    return lines;
+}
+/**
+ * The `── Permissions ──` section: one row per vector, and for each the STATE,
+ * the PROVENANCE (which identity actually holds the grant — the question the
+ * three summary rows above cannot answer), and the remediation when it is
+ * missing (docs/design/permissions-doctrine.md, Article II).
+ *
+ * Every value here comes from the prompt-free verdict `diagnose` already took.
+ * Doctor was an Article I violation once — it opened the container to find out
+ * whether it could — and this section must never regress that: it renders, it
+ * does not probe.
+ */
+function permissionLines(report) {
+    const { read, write, ui } = report.capability;
+    const hostLabel = read.host.bundleId !== null ? `${read.host.name} (${read.host.bundleId})` : read.host.name;
+    const readProvenance = () => {
+        switch (read.mode) {
+            case "helpers":
+                return "reader bookmark (things-reader)";
+            case "direct-fda":
+                return `host Full Disk Access (${hostLabel})`;
+            case "session-grant":
+                return `session marker (${hostLabel}, until it quits)`;
+            case "explicit-db":
+                return "none needed (an explicit --db path)";
+            default:
+                return "none";
+        }
+    };
+    const writeProvenance = () => {
+        switch (write.mode) {
+            case "deputy":
+                return "deputy TCC Automation (Things API Helper)";
+            case "direct-granted":
+                return `host TCC Automation (${hostLabel})`;
+            default:
+                return "none";
+        }
+    };
+    const uiProvenance = () => {
+        switch (ui.mode) {
+            case "helpers":
+                return "deputy TCC Accessibility + System Events (Things API Helper)";
+            case "direct-escape":
+                return "the lab's direct escape (not consumer surface)";
+            default:
+                return "none — helpers only (Article IV)";
+        }
+    };
+    const rows = [
+        {
+            vector: "read",
+            state: read.mode,
+            provenance: readProvenance(),
+            next: read.remediation,
+        },
+        {
+            vector: "applescript",
+            state: write.mode,
+            provenance: writeProvenance(),
+            next: write.remediation,
+        },
+        {
+            vector: "url-scheme",
+            state: report.availability.urlScheme.enabled === true
+                ? "enabled"
+                : report.availability.urlScheme.enabled === false
+                    ? "disabled"
+                    : "unknown",
+            // No TCC class at all: `open -g things:///…` is a LaunchServices dispatch.
+            provenance: "none needed — the app's own 'Enable Things URLs' setting",
+            next: report.availability.urlScheme.enabled === true
+                ? []
+                : ["turn on Things ▸ Settings ▸ General ▸ Enable Things URLs"],
+        },
+        {
+            vector: "shortcuts",
+            state: report.availability.shortcuts.missing.length === 0
+                ? "installed"
+                : `${report.availability.shortcuts.present.length}/${report.availability.shortcuts.present.length +
+                    report.availability.shortcuts.missing.length} installed`,
+            provenance: "none needed — each shortcut's own Always Allow",
+            next: report.availability.shortcuts.missing.length === 0
+                ? []
+                : ["run `things setup` to install the missing proxy shortcuts"],
+        },
+        { vector: "ui", state: ui.mode, provenance: uiProvenance(), next: ui.remediation },
+    ];
+    const vectorWidth = Math.max(...rows.map((r) => r.vector.length));
+    const stateWidth = Math.max(...rows.map((r) => r.state.length));
+    const lines = ["── Permissions (per vector) ──", `host app:    ${hostLabel}`];
+    for (const row of rows) {
+        lines.push(`  ${row.vector.padEnd(vectorWidth)}  ${row.state.padEnd(stateWidth)}  ${row.provenance}`);
+        for (const next of row.next)
+            lines.push(`${" ".repeat(vectorWidth + stateWidth + 6)}next: ${next}`);
+    }
+    return lines;
+}
 function environmentLine(env) {
     if (env.lastVerifiedWrite === null) {
         return "no verified write recorded yet (the tuple is recorded on the first successful write)";
@@ -21,6 +136,66 @@ function syncHealthLines(sh) {
         `cloud:       ${sh.cloud.verdict}`,
     ];
 }
+/** One half's line: liveness, launchd registration, version, signing. */
+function helperHalfLine(half, running) {
+    const facts = [
+        half.plistInstalled
+            ? half.loaded
+                ? "launchd loaded"
+                : "launchd registered, NOT loaded"
+            : "no launchd registration",
+    ];
+    if (half.hello !== null) {
+        facts.push(`v${half.hello.deputyVersion}, protocol ${half.hello.protocol}, pid ${half.hello.pid}`);
+        // Only the deputy carries TCC standing, and only from helpers v1.2.0 on —
+        // an older one simply has no row here rather than a guessed one.
+        if (half.hello.automation !== undefined) {
+            facts.push(`automation: Things ${half.hello.automation.things}, System Events ${half.hello.automation.systemEvents}`);
+        }
+        if (half.hello.axTrusted !== undefined) {
+            facts.push(`accessibility: ${half.hello.axTrusted ? "granted" : "NOT granted"}`);
+        }
+    }
+    if (half.signing !== null) {
+        facts.push(half.signing.state === "signed"
+            ? `signed (${half.signing.authority ?? "unknown authority"})`
+            : `${half.signing.state} — macOS grants will NOT survive rebuilds`);
+    }
+    return `${running} · ${facts.join(" · ")}`;
+}
+/** The `── Helpers ──` section: routing resolution + both halves' health. */
+function helpersLines(helpers) {
+    const { status, routing } = helpers;
+    const resolved = helpers.mode === "false"
+        ? "direct (routing off)"
+        : `automation ${routing.automation ? "via the deputy" : "DIRECT"}, database reads ${routing.files ? "via the reader" : "DIRECT"}`;
+    const lines = [
+        "── Helpers ──",
+        `mode:        ${helpers.mode} — ${helpers.detail}`,
+        `routing:     ${resolved}`,
+        `bundle:      ${status.bundleInstalled
+            ? `installed${helpers.installedVersion !== null ? ` (v${helpers.installedVersion})` : ""}${helpers.versionSkew ? `, this package expects v${helpers.expectedVersion}` : ""}`
+            : "not installed"}`,
+    ];
+    if (status.bundleInstalled || status.deputy.plistInstalled) {
+        lines.push(`deputy:      ${helperHalfLine(status.deputy, status.deputy.running
+            ? "running"
+            : status.deputy.hungSocket
+                ? "SOCKET PRESENT, NOT ANSWERING"
+                : "not running")}`, `reader:      ${status.reader.installed
+            ? helperHalfLine(status.reader, status.reader.running
+                ? status.reader.granted
+                    ? "running, granted"
+                    : "running, NOT granted"
+                : status.reader.hungSocket
+                    ? "SOCKET PRESENT, NOT ANSWERING"
+                    : "not running")
+            : "not installed (the bundle was built without an Apple-issued signing identity)"}`);
+    }
+    if (helpers.remedy !== null)
+        lines.push(`next:        ${helpers.remedy}`);
+    return lines;
+}
 /** The `── ui vector ──` section: config + app + Accessibility + certification. */
 function uiVectorLines(ui) {
     const total = ui.certification.length;
@@ -42,9 +217,10 @@ export function registerDoctor(program) {
         .description("Check environment health: database location, database schema compatibility, app " +
         "presence, any one-time setup still needed (macOS permissions, the app's " +
         "'Enable Things URLs' setting), whether the environment changed since the last " +
-        "successful write, and a sync-health summary (whether the app is running, how recently " +
+        "successful write, a sync-health summary (whether the app is running, how recently " +
         "the data changed, and — when a Things Cloud account is attached — the last sync " +
-        "attempt) — with steps to fix. " +
+        "attempt), and the state of the optional helpers (installed, running, granted, signed, " +
+        "and what routing resolved to) — with steps to fix. " +
         "Exit 0 healthy; 5 schema drift (writes disabled); 7 environment problem.")
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path (overrides THINGS_DB and discovery)")
@@ -67,6 +243,7 @@ export function registerDoctor(program) {
         }
         else if (report) {
             const lines = [
+                ...capabilityLines(report.capability),
                 `db:          ${report.db.path} (${report.db.source})`,
                 `db version:  ${report.db.databaseVersion ?? "unknown"}`,
                 `fingerprint: ${report.fingerprint.status} (${report.fingerprint.value.slice(0, 23)}…)`,
@@ -102,6 +279,8 @@ export function registerDoctor(program) {
                     ]
                     : []),
                 ...syncHealthLines(report.syncHealth),
+                ...permissionLines(report),
+                ...helpersLines(report.helpers),
                 ...uiVectorLines(report.ui),
             ];
             process.stdout.write(`${lines.join("\n")}\n`);