@trygocode/notify 0.4.0 → 0.6.0

package/dist/src/desktop_notify.js

@@ -39,6 +39,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { appendLog } from "./send.js";
 import { gocodeDir } from "./creds.js";
+import { cachedAuthStatus, notifyViaMacHelper, requestMacPermission, } from "./mac_helper.js";
 /** Default banner timeout (PRD §2.4: 5s hard cap, same as the phone `send`). */
 export const DEFAULT_DESKTOP_TIMEOUT_MS = 5000;
 /** The Windows AppUserModelID the branded toast binds to (PRD §2.3). */
@@ -50,8 +51,22 @@ export const APP_NAME = "GoCode";
  * AppleScript changes (e.g. the click handler added in 0.5.0) so an existing
  * install's stale `GoCode.app` is recompiled once instead of silently reused.
  * Tracked via a `~/.gocode/desktop/.bundle-v<N>` marker file.
+ *
+ * v3 (2026-06-20): inject a stable CFBundleIdentifier + register with
+ * LaunchServices. macOS 15/26 silently DROP notifications from an app bundle
+ * with no bundle id (osacompile's default applet has none), which is why
+ * banners "succeeded" (osascript exit 0) but never appeared. Bumped so existing
+ * id-less bundles get rebuilt once with the fix.
+ */
+export const MAC_BUNDLE_VERSION = 3;
+/**
+ * Stable CFBundleIdentifier stamped into the compiled `GoCode.app`. macOS keys
+ * notification authorization (System Settings → Notifications) off this id, so
+ * it MUST be stable across rebuilds for the user's "Allow" grant to persist and
+ * for the app to even appear in the Notifications list. Reverse-DNS, matches
+ * the GoCode brand namespace.
  */
-export const MAC_BUNDLE_VERSION = 2;
+export const MAC_BUNDLE_ID = "com.gocode.notify.desktop";
 /**
  * Env var that hard-disables ALL desktop banners regardless of settings — a
  * machine-level opt-out for headless servers, CI, SSH sessions, or any box where
@@ -225,6 +240,123 @@ export async function notifyDesktop(payload, opts = {}) {
         return { ok: false, platform: "unsupported", error: `unexpected error: ${msg}` };
     }
 }
+/**
+ * Make the OS notification-permission UI appear for GoCode, so the user grants
+ * permission with a click instead of hunting through Settings.
+ *
+ * macOS (since 0.6.0 — the SIGNED helper changed this): we now ship a
+ * Developer-ID-signed `GoCodeNotifier.app` in the package, so we CAN pop the real
+ * native Allow/Deny MODAL via `UNUserNotificationCenter.requestAuthorization`.
+ * The flow is:
+ *   1. Try the signed helper's `request-permission` (see mac_helper.ts). On a
+ *      real grant we're DONE — no Settings hunt, and a confirming banner fires.
+ *   2. If the signed helper is UNAVAILABLE (non-macOS publish / missing bundle)
+ *      or the user previously DENIED (macOS won't re-prompt), fall back to the
+ *      legacy reliable next-best thing: register the branded applet, open
+ *      **System Settings → Notifications** (deep-link), and fire a priming
+ *      banner so the GoCode toggle is one tap away.
+ * On Windows/Linux notifications don't gate behind a per-app grant the same
+ * way, so this just fires a priming banner and reports success.
+ *
+ * Best-effort + total: never throws; always resolves to a {@link PermissionResult}.
+ */
+export async function requestDesktopPermission(opts = {}) {
+    const platform = (opts.platform ?? process.platform);
+    const run = opts.run ?? defaultRunner;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_DESKTOP_TIMEOUT_MS;
+    const logLine = async (line) => {
+        try {
+            if (opts.log)
+                await opts.log(line);
+            else
+                await appendLog(`PERMISSION: ${line}`, { home: opts.home, timestamp: opts.timestamp });
+        }
+        catch {
+            // logging must never block
+        }
+    };
+    if (platform !== "darwin") {
+        // Prime a banner so the app is registered; no per-app grant gate to open.
+        const primed = await notifyDesktop({ title: APP_NAME, body: "GoCode notifications are enabled.", sound: false }, opts);
+        const message = primed.ok
+            ? "Fired a test banner — desktop notifications are working."
+            : `Could not fire a test banner (${primed.error ?? "unknown"}).`;
+        // Log the outcome too (parity with the macOS branch) so the `permissions`
+        // command leaves a breadcrumb on Linux / unsupported notification setups.
+        await logLine(message);
+        return {
+            platform: primed.platform,
+            openedSettings: false,
+            primed: primed.ok,
+            message,
+        };
+    }
+    // macOS path.
+    //
+    // PREFERRED (2026-06-20): pop the REAL native Allow/Deny modal via the
+    // Developer-ID-SIGNED helper. Unlike the legacy `osacompile` applet (which
+    // can't request authorization at all), the signed app calls
+    // UNUserNotificationCenter.requestAuthorization, which shows the system modal
+    // the first time and persists the user's choice. We try this first; if it
+    // genuinely grants (or the user already granted), we're DONE — no Settings
+    // hunt needed. If the signed helper is unavailable (non-macOS publish, missing
+    // bundle) or the user previously denied, we fall back to the legacy
+    // open-Settings + priming-banner nudge below.
+    // `skipSignedHelper` (tests / hard opt-out) makes this resolve as unavailable
+    // so we go straight to the legacy open-Settings + priming-banner fallback.
+    const helper = opts.skipSignedHelper
+        ? { ok: false, status: "unknown", unavailable: true }
+        : await requestMacPermission({
+            home: opts.home,
+            run,
+            timeoutMs: opts.timeoutMs,
+            log: logLine,
+            platform: "darwin",
+            bundledAppPath: opts.bundledAppPath,
+        }, opts.helperVersionTag);
+    if (!helper.unavailable && (helper.status === "authorized" || helper.granted === true)) {
+        const msg = "Showed the native macOS permission dialog — GoCode desktop notifications are now allowed.";
+        await logLine(msg);
+        // Also fire a confirming banner so the user immediately sees a real one.
+        await notifyDesktop({ title: APP_NAME, body: "Desktop notifications are on. You’ll get a banner when your agent finishes.", sound: true }, opts).catch(() => undefined);
+        return { platform: "darwin", openedSettings: false, primed: true, message: msg };
+    }
+    let openedSettings = false;
+    try {
+        // Open System Settings straight to the Notifications pane (deep-link). The
+        // modern URL; falls back silently if the OS doesn't honour it.
+        const opened = await run("open", ["x-apple.systempreferences:com.apple.preference.notifications"], {
+            timeoutMs,
+        });
+        openedSettings = opened.code === 0;
+        if (!openedSettings) {
+            await logLine(`could not open Notifications settings (open exit ${opened.code})`);
+        }
+    }
+    catch (err) {
+        await logLine(`open Settings threw — ignored: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Fire a priming banner — this both verifies the path AND nudges macOS to
+    // register the (now bundle-id-stamped) app into the Notifications list.
+    const primed = await notifyDesktop({
+        title: APP_NAME,
+        body: "Tap “Allow” for GoCode in System Settings → Notifications to get desktop alerts.",
+        sound: true,
+    }, opts);
+    // If the signed helper was present but the user had previously DENIED, say so
+    // explicitly — they must re-enable it in Settings (macOS won't re-prompt).
+    const deniedNote = !helper.unavailable && helper.status === "denied"
+        ? "GoCode notifications are currently turned OFF — re-enable them in System Settings → Notifications → GoCode. "
+        : "";
+    const message = primed.ok
+        ? deniedNote +
+            (openedSettings
+                ? "Opened System Settings → Notifications and fired a test banner. Turn ON “Allow Notifications” for GoCode."
+                : "Fired a test banner. Open System Settings → Notifications and turn ON “Allow Notifications” for GoCode.")
+        : `${deniedNote}Could not fire the priming banner (${primed.error ?? "unknown"}). Open System Settings → Notifications and enable GoCode manually.`;
+    await logLine(message);
+    return { platform: "darwin", openedSettings, primed: primed.ok, message };
+}
 // ── macOS ────────────────────────────────────────────────────────────────────
 /** Path to the branded helper app bundle under `~/.gocode/desktop/GoCode.app`. */
 export function macAppPath(opts) {
@@ -338,6 +470,14 @@ export async function ensureMacBrandedApp(ctx) {
         // bundled PNG → icns via `sips` (ships with macOS); if that fails the banner
         // is still branded by NAME ("GoCode") which is the important part.
         await brandMacIcon(appPath, ctx).catch(() => { });
+        // CRITICAL (2026-06-20): give the bundle a stable CFBundleIdentifier and
+        // register it with LaunchServices. macOS 15/26 silently DROP notifications
+        // from a bundle with no identifier — osacompile's default applet ships none,
+        // which is why banners reported success but never appeared. This makes the
+        // app authorizable + visible in System Settings → Notifications so the OS
+        // can persist the user's "Allow" grant. Best-effort: a failure here just
+        // means the banner may still be suppressed (degrade, never block).
+        await ensureMacBundleIdentity(appPath, ctx).catch(() => { });
         // Stamp the version marker so we don't recompile until the bundle changes.
         // Clear any older `.bundle-v*` markers first so the dir doesn't accumulate.
         try {
@@ -379,6 +519,50 @@ async function brandMacIcon(appPath, ctx) {
         await ctx.log(`icon conversion skipped (sips code ${res.code}) — banner is name-branded only`);
     }
 }
+/**
+ * Stamp a stable `CFBundleIdentifier` into the compiled applet's Info.plist and
+ * register the bundle with LaunchServices.
+ *
+ * WHY (2026-06-20): `osacompile` produces an applet whose Info.plist has NO
+ * `CFBundleIdentifier`. On macOS 15/26 the notification system keys
+ * authorization off the bundle id, so an id-less app is treated as
+ * un-authorizable and its `display notification` banners are silently dropped
+ * (the `osascript`/applet call still exits 0 — it "posted" — so nothing looked
+ * wrong from our side). Stamping a stable id makes the app:
+ *   1. appear in System Settings → Notifications (so the user can Allow it), and
+ *   2. retain that grant across rebuilds (the id is stable, see {@link MAC_BUNDLE_ID}).
+ * We then `lsregister -f` the bundle so the OS picks it up immediately rather
+ * than waiting for a Spotlight/LaunchServices sweep.
+ *
+ * Best-effort + total: never throws (caller wraps in `.catch`), and any failure
+ * just leaves the banner possibly-suppressed rather than blocking the hook.
+ */
+export async function ensureMacBundleIdentity(appPath, ctx) {
+    const plist = path.join(appPath, "Contents", "Info.plist");
+    // PlistBuddy ships with every macOS. `Set` updates an existing key; if the
+    // key is absent (osacompile's applet has none) `Set` fails, so try `Add`.
+    const setRes = await ctx.run("/usr/libexec/PlistBuddy", ["-c", `Set :CFBundleIdentifier ${MAC_BUNDLE_ID}`, plist], { timeoutMs: ctx.timeoutMs });
+    if (setRes.code !== 0) {
+        const addRes = await ctx.run("/usr/libexec/PlistBuddy", ["-c", `Add :CFBundleIdentifier string ${MAC_BUNDLE_ID}`, plist], { timeoutMs: ctx.timeoutMs });
+        if (addRes.code !== 0) {
+            await ctx.log(`could not stamp CFBundleIdentifier (PlistBuddy ${addRes.code}): ${addRes.stderr.trim()} — notifications may be suppressed by macOS`);
+            // No id → registering is pointless; bail (the banner may still be dropped,
+            // but we've logged the actionable reason).
+            return;
+        }
+    }
+    // Register the bundle with LaunchServices so the OS recognises it as an app
+    // that can post notifications, NOW (not after a background sweep). `-f` forces
+    // a (re)register of this exact path.
+    const lsregister = "/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister";
+    const reg = await ctx.run(lsregister, ["-f", appPath], { timeoutMs: ctx.timeoutMs });
+    if (reg.code !== 0) {
+        await ctx.log(`lsregister returned ${reg.code} — bundle may not appear in Notification settings immediately`);
+    }
+    else {
+        await ctx.log(`stamped CFBundleIdentifier ${MAC_BUNDLE_ID} + registered bundle with LaunchServices`);
+    }
+}
 /**
  * Write (or clear) the click-target file the applet reads on a banner click
  * (PRD §3.6). When `click` is set we write a single tab-separated line
@@ -402,6 +586,53 @@ function oneLine(s) {
     return s.replace(/[\t\r\n]+/g, " ").trim();
 }
 async function notifyMac(banner, ctx) {
+    // PREFERRED path (2026-06-20): the Developer-ID-SIGNED helper app. It posts a
+    // first-class UserNotifications banner from a properly-authorized app and
+    // carries a real click action. Only used when the user has actually granted
+    // notification permission to the signed helper (status "authorized") — if they
+    // haven't (notDetermined/denied), a signed-helper post would silently no-op,
+    // so we fall through to the legacy applet which still shows *something*. We do
+    // NOT request authorization here (that's the `permissions`/`setup` flow's job,
+    // where there's a human to click Allow); a fire-and-forget banner must never
+    // pop a modal. Best-effort: any failure falls through to the applet.
+    if (!ctx.skipBranding && !ctx.skipSignedHelper) {
+        try {
+            // Read the CACHED auth status (a cheap file read) — never a live
+            // `open`+poll round-trip on the hot fire-and-forget path. The cache is
+            // populated by the `permissions`/`setup` flow when the user grants. No
+            // cache (or not "authorized") → fall through to the applet.
+            const cached = await cachedAuthStatus(ctx);
+            if (cached === "authorized") {
+                // KNOWN LIMITATION (signed-banner click-through): the signed helper exits
+                // ~0.4s after posting, so its in-process click delegate is gone by the
+                // time a user actually clicks the banner; a click then relaunches the app
+                // with no args (→ a no-op `status` run) and does NOT route to the IDE. We
+                // still pass the click target on the notification's userInfo (harmless),
+                // but reliable click-to-open remains the legacy applet's job. The signed
+                // path's win is the real Allow dialog + correct "GoCode" attribution; if
+                // a guaranteed click action matters more than attribution for a given
+                // banner, the applet fallback (below) handles the click via click-target.tsv.
+                if (banner.click) {
+                    await writeMacClickTarget(banner.click, ctx).catch(() => { });
+                }
+                const posted = await notifyViaMacHelper({
+                    title: banner.title,
+                    body: banner.body,
+                    sound: banner.sound,
+                    clickApp: banner.click?.app,
+                    clickPath: banner.click?.projectPath,
+                }, { home: ctx.home, run: ctx.run, timeoutMs: ctx.timeoutMs, log: ctx.log, platform: "darwin" }, ctx.helperVersionTag);
+                if (posted.ok) {
+                    await ctx.log(`signed-helper banner shown (${banner.title})`);
+                    return { ok: true, platform: "darwin" };
+                }
+                await ctx.log(`signed-helper banner failed (${posted.detail ?? posted.status}) — falling back to applet`);
+            }
+        }
+        catch (err) {
+            await ctx.log(`signed-helper path errored (${err instanceof Error ? err.message : String(err)}) — falling back to applet`);
+        }
+    }
     // Branded path: invoke the compiled GoCode.app applet so the banner is
     // attributed to "GoCode" (+ our icon) instead of "Script Editor".
     if (!ctx.skipBranding) {

package/dist/src/doctor.js

@@ -193,14 +193,33 @@ export async function gatherDoctor(opts = {}) {
     // ── 3c. Cursor stop hook ───────────────────────────────────────────────
     const cursorHooksPath = path.join(home, ".cursor", "hooks.json");
     const cursorHooks = await readJsonFile(cursorHooksPath);
-    // Pass the stop array directly (not wrapped in an object) so extractCommands
-    // can find the {command: ...} entries inside it.
-    const cursorStopValue = cursorHooks &&
-        typeof cursorHooks === "object" &&
-        "stop" in cursorHooks
-        ? cursorHooks.stop
+    // Cursor's hooks.json nests the events under a top-level `hooks` key:
+    //   { "version": 1, "hooks": { "stop": [ { "command": ... } ] } }
+    // Older/loose configs put `stop` at the top level. Scan `stop` from BOTH
+    // locations (combining their commands) so the doctor doesn't false-negative
+    // on the real nested schema — that bug made it report "hook not found" even
+    // when the hook was correctly installed (2026-06-20) — AND so a mixed config
+    // carrying a top-level `stop` is still detected even when a nested `hooks`
+    // object exists for other events.
+    const cursorRoot = cursorHooks && typeof cursorHooks === "object"
+        ? cursorHooks
         : null;
-    const cursorStopEntries = flattenHookCommands(cursorStopValue);
+    const cursorNestedHooks = cursorRoot &&
+        "hooks" in cursorRoot &&
+        cursorRoot.hooks &&
+        typeof cursorRoot.hooks === "object"
+        ? cursorRoot.hooks
+        : null;
+    const cursorStopEntries = [
+        // Nested `hooks.stop` (current Cursor schema).
+        ...(cursorNestedHooks && "stop" in cursorNestedHooks
+            ? flattenHookCommands(cursorNestedHooks.stop)
+            : []),
+        // Top-level `stop` (older/loose schema).
+        ...(cursorRoot && "stop" in cursorRoot
+            ? flattenHookCommands(cursorRoot.stop)
+            : []),
+    ];
     const cursorStopInstalled = cursorStopEntries.some((c) => c.includes(CURSOR_HOOK_TOKEN));
     checks.push({
         key: "hook:cursor-stop",

package/dist/src/mac_helper.js

@@ -0,0 +1,335 @@
+// `mac_helper` — the bridge to the Developer-ID-SIGNED macOS notifier app bundle
+// (`GoCodeNotifier.app`) shipped pre-signed inside the npm tarball under
+// `assets/`. This is the ONE thing the zero-dependency `osacompile` applet could
+// never do: pop the real native "“GoCode” Would Like to Send You Notifications ·
+// Allow / Don't Allow" authorization modal, and post first-class
+// UserNotifications banners from a properly-authorized signed app.
+//
+// WHY A SEPARATE MODULE (and why it's all best-effort):
+//   `desktop_notify.ts` owns the legacy unsigned-applet path (always available,
+//   posts banners, but CANNOT request authorization). This module owns the
+//   SIGNED path. The two TWO HARD macOS rules below were both confirmed
+//   empirically (2026-06-20) and are the reason this isn't a one-liner:
+//
+//     1. LAUNCH VIA LaunchServices, NEVER exec the inner binary.
+//        Running `…/GoCodeNotifier.app/Contents/MacOS/GoCodeNotifier` directly
+//        bypasses LaunchServices and macOS AUTO-DENIES the authorization request
+//        (and that denial STICKS). We must launch with `open <app> --args …`.
+//        Because `open` discards the child's stdout, the helper writes its JSON
+//        result to a file we pass via `GOCODE_RESULT_FILE` and we read THAT.
+//
+//     2. RUN FROM A STABLE LOCATION, NEVER /tmp (or a volatile npm cache).
+//        Launching the bundle from `/tmp` yields "Notifications are not allowed
+//        for this application". So on first use we COPY the signed bundle out of
+//        the package's `assets/` into `~/.gocode/desktop/GoCodeNotifier.app`
+//        (stable, user-owned) and run it from there. Copying preserves the
+//        embedded code signature (it's just files), so it stays Developer-ID
+//        valid. We then `lsregister -f` it so the OS recognises it immediately.
+//
+// CONTRACT: every export is best-effort + total — never throws, always resolves
+// to a structured result. A missing bundle / unsupported platform / wedged child
+// resolves to `{ ok:false, … }` so the caller cleanly falls back to the unsigned
+// applet. This module owns NO gating policy — callers decide whether to use it.
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { desktopDir, defaultRunner } from "./desktop_notify.js";
+import { VERSION } from "./version.js";
+/**
+ * Stable CFBundleIdentifier of the SIGNED helper. DISTINCT from the legacy
+ * applet's `com.gocode.notify.desktop` on purpose: the signed app owns its own
+ * notification-authorization identity in System Settings → Notifications, so a
+ * poisoned/denied decision on the old shared id can never block the signed
+ * grant. MUST match the CFBundleIdentifier in
+ * `native/macos/GoCodeNotifier/Info.plist` + `build_and_sign.sh`.
+ */
+export const HELPER_BUNDLE_ID = "com.gocode.notify.helper";
+/** The signed app bundle's name (same in `assets/` and at the runtime location). */
+export const HELPER_APP_NAME = "GoCodeNotifier.app";
+/** The executable inside the bundle (Contents/MacOS/<this>). */
+export const HELPER_EXECUTABLE = "GoCodeNotifier";
+/** Hard cap for a helper invocation. The Swift side also self-times-out. */
+export const DEFAULT_HELPER_TIMEOUT_MS = 30000;
+// ── path resolution ──────────────────────────────────────────────────────────
+/**
+ * Resolve the SIGNED `GoCodeNotifier.app` shipped in the package's `assets/` dir.
+ * The compiled module lives at `dist/src/mac_helper.js`, so `assets/` is two
+ * levels up. Returns the bundle path (which may not exist on a non-macOS publish
+ * or a partial install — callers check existence). Mirrors `bundledIconPath`.
+ */
+export function bundledHelperAppPath() {
+    const here = path.dirname(fileURLToPath(import.meta.url)); // dist/src
+    return path.resolve(here, "..", "..", "assets", HELPER_APP_NAME);
+}
+/**
+ * The STABLE runtime location we copy the signed bundle to before running it
+ * (`~/.gocode/desktop/GoCodeNotifier.app`). Running from here — never `/tmp` and
+ * never the volatile npm cache — is REQUIRED for macOS to allow the app to
+ * request notification authorization (see module header rule 2).
+ */
+export function installedHelperAppPath(opts) {
+    return path.join(desktopDir(opts), HELPER_APP_NAME);
+}
+/** The signed helper's executable at the stable runtime location. */
+export function installedHelperBinPath(opts) {
+    return path.join(installedHelperAppPath(opts), "Contents", "MacOS", HELPER_EXECUTABLE);
+}
+/** Marker recording which package version's bundle we last installed (for upgrades). */
+function installedMarkerPath(opts) {
+    return path.join(desktopDir(opts), ".helper-installed");
+}
+/**
+ * Cache file for the last-known authorization status. The fire-and-forget banner
+ * path reads THIS (a cheap file read) instead of doing a full `open`+poll
+ * round-trip on every notification — a live status query costs ~1s+ which is far
+ * too slow for a hook. The cache is written whenever we DO run the helper
+ * (`request-permission` / `status`), so it tracks the user's real decision; if
+ * the user later flips the toggle in System Settings the cache self-heals the
+ * next time the permission/status path runs (and a stale "authorized" only means
+ * one wasted signed-post that silently falls through to the applet anyway).
+ */
+export function authStatusCachePath(opts) {
+    return path.join(desktopDir(opts), ".auth-status");
+}
+/** Persist the last-known auth status (best-effort; failure is non-fatal). */
+async function writeAuthStatusCache(status, opts) {
+    try {
+        await fs.mkdir(desktopDir(opts), { recursive: true, mode: 0o700 });
+        await fs.writeFile(authStatusCachePath(opts), status, { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // cache is an optimization — never fail the flow over it
+    }
+}
+/**
+ * Read the cached authorization status WITHOUT running the helper (fast). Returns
+ * undefined when there is no cache yet (then the banner path uses the applet
+ * until the user runs the permission flow once). This is what `notifyMac` calls
+ * on the hot path.
+ */
+export async function cachedAuthStatus(opts) {
+    try {
+        const raw = (await fs.readFile(authStatusCachePath(opts), "utf8")).trim();
+        return raw ? raw : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ── ensure the signed bundle is installed at the stable location ──────────────
+/**
+ * Copy the package's signed `GoCodeNotifier.app` to the stable runtime location
+ * (`~/.gocode/desktop/`) if it isn't there (or is stale for this package
+ * version), then register it with LaunchServices so the OS recognises it
+ * immediately. Idempotent. Returns the installed bundle path on success, or
+ * undefined when the signed bundle isn't available to copy (then the caller
+ * falls back to the unsigned applet).
+ *
+ * Copying preserves the embedded Developer-ID code signature (it's just a tree
+ * of files) — `cp -R` keeps the `_CodeSignature` dir + signed Mach-O intact.
+ */
+export async function ensureHelperInstalled(opts = {}, versionTag = VERSION) {
+    const run = opts.run ?? defaultRunner;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_HELPER_TIMEOUT_MS;
+    const src = opts.bundledAppPath ?? bundledHelperAppPath();
+    const dest = installedHelperAppPath(opts);
+    const destBin = installedHelperBinPath(opts);
+    const marker = installedMarkerPath(opts);
+    // The signed bundle must exist in the package to install it.
+    try {
+        await fs.access(src);
+    }
+    catch {
+        await opts.log?.(`signed helper not bundled at ${src} — using unsigned applet`);
+        return undefined;
+    }
+    // Already installed AND current for this package version? → reuse.
+    try {
+        await fs.access(destBin);
+        const tag = await fs.readFile(marker, "utf8").catch(() => "");
+        if (tag.trim() === versionTag)
+            return dest;
+    }
+    catch {
+        // need to (re)install — missing bin or stale/absent marker
+    }
+    try {
+        await fs.mkdir(desktopDir(opts), { recursive: true, mode: 0o700 });
+        // Remove any stale copy so a partial/older bundle can't linger.
+        await fs.rm(dest, { recursive: true, force: true }).catch(() => { });
+        // `cp -R` preserves the code signature; Node's fs.cp also works but we use
+        // the injectable runner so tests can stub it without touching the disk.
+        const cp = await run("cp", ["-R", src, dest], { timeoutMs });
+        if (cp.code !== 0) {
+            await opts.log?.(`could not copy signed helper (cp ${cp.code}): ${cp.stderr.trim()} — using unsigned applet`);
+            return undefined;
+        }
+        // Register with LaunchServices so the OS picks it up NOW (not after a sweep).
+        const lsregister = "/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister";
+        await run(lsregister, ["-f", dest], { timeoutMs }).catch(() => ({ code: 1, stdout: "", stderr: "" }));
+        await fs.writeFile(marker, versionTag, { encoding: "utf8", mode: 0o600 }).catch(() => { });
+        return dest;
+    }
+    catch (err) {
+        await opts.log?.(`signed helper install error: ${err instanceof Error ? err.message : String(err)} — using unsigned applet`);
+        return undefined;
+    }
+}
+// ── run the installed signed helper via LaunchServices ────────────────────────
+/** True on macOS — the only platform the signed helper targets. */
+function isMac(opts) {
+    return (opts.platform ?? process.platform) === "darwin";
+}
+/** A result meaning "we couldn't run the signed path; fall back to the applet". */
+function unavailable(detail) {
+    return { ok: false, status: "unknown", detail, unavailable: true };
+}
+/**
+ * Launch the installed signed helper via `open <app> --args …` (LaunchServices —
+ * the ONLY way macOS will let it request authorization), capturing its JSON
+ * result through a temp `GOCODE_RESULT_FILE` (because `open` discards the child's
+ * stdout). Polls the result file until the helper writes it or we hit the
+ * timeout. Best-effort + total: any failure resolves to a structured
+ * {@link HelperResult}, never throws.
+ *
+ * @param command  the helper subcommand: "request-permission" | "notify" | "status"
+ * @param extraArgs additional `--flag value` pairs for the helper
+ */
+export async function runHelper(command, extraArgs, opts = {}, versionTag = VERSION) {
+    if (!isMac(opts))
+        return unavailable("signed helper is macOS-only");
+    const run = opts.run ?? defaultRunner;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_HELPER_TIMEOUT_MS;
+    const appPath = await ensureHelperInstalled(opts, versionTag);
+    if (!appPath)
+        return unavailable("signed helper not installed");
+    // A unique result file per call so concurrent invocations don't clobber.
+    const resultFile = path.join(os.tmpdir(), `gocode-helper-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+    // `open -n` launches a FRESH instance via launchd. CRITICAL: a LaunchServices
+    // launch does NOT inherit arbitrary env vars from THIS process — env passed to
+    // the `open` subprocess is the `open` tool's own env, not the launched app's.
+    // The supported way to inject a per-launch env var into the launched app is
+    // `open --env NAME=VALUE` (see open(1)); we use that so the Swift helper
+    // reliably sees GOCODE_RESULT_FILE and writes its JSON result there. We poll
+    // that file rather than `-W` (which can hang for the click window). We ALSO
+    // keep the var in the subprocess env as a belt-and-braces fallback for any OS
+    // where the flag is unsupported, but `--env` is the load-bearing path.
+    const args = [
+        "-n",
+        "--env",
+        `GOCODE_RESULT_FILE=${resultFile}`,
+        appPath,
+        "--args",
+        command,
+        ...extraArgs,
+    ];
+    const launch = await run("open", args, {
+        timeoutMs,
+        env: { GOCODE_RESULT_FILE: resultFile },
+    });
+    if (launch.code !== 0) {
+        await opts.log?.(`open failed to launch signed helper (code ${launch.code}): ${launch.stderr.trim()}`);
+        return unavailable(`open exit ${launch.code}`);
+    }
+    // Poll for the helper's JSON result. It writes the file as its LAST act, so a
+    // present-and-parseable file means the operation finished. Cap polling at the
+    // timeout; the Swift side has its own hard self-timeout so this can't run away.
+    const deadline = Date.now() + timeoutMs;
+    // Track the last "the file exists but I couldn't parse it" reason so a
+    // persistent malformed/truncated result is surfaced on timeout instead of a
+    // bare "timed out" (which would hide the real cause). A plain ENOENT — the
+    // helper simply hasn't written yet — is NOT logged (that's the normal poll).
+    let lastParseError;
+    // A non-ENOENT read failure (EACCES/ENOTDIR/etc.) — distinct from the normal
+    // "not written yet" ENOENT — so a persistent read problem is diagnosable.
+    let lastReadError;
+    while (Date.now() < deadline) {
+        let raw;
+        try {
+            raw = await fs.readFile(resultFile, "utf8");
+        }
+        catch (err) {
+            // ENOENT is the NORMAL case — the helper hasn't written the file yet, so
+            // retry quietly. Any OTHER errno (EACCES, ENOTDIR, an unexpected tmpdir
+            // problem) is NOT normal: record it so a persistent read failure surfaces
+            // in the timeout detail instead of masquerading as a generic timeout.
+            const code = err?.code;
+            if (code !== "ENOENT") {
+                lastReadError = err instanceof Error ? err.message : String(err);
+            }
+            await delay(150);
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(raw.trim());
+            await fs.rm(resultFile, { force: true }).catch(() => { });
+            // Refresh the auth-status cache when this run reported an authorization
+            // status (request-permission / status). `notify` reports "posted", which
+            // we deliberately do NOT cache as an auth status.
+            if (command !== "notify" &&
+                ["authorized", "denied", "notDetermined", "provisional", "ephemeral"].includes(parsed.status)) {
+                await writeAuthStatusCache(parsed.status, opts);
+            }
+            return parsed;
+        }
+        catch (err) {
+            // The file EXISTS but didn't parse — likely a mid-write truncation, so
+            // retry; but remember the reason so a persistent bad result is reported.
+            lastParseError = err instanceof Error ? err.message : String(err);
+            await delay(150);
+        }
+    }
+    await fs.rm(resultFile, { force: true }).catch(() => { });
+    // Surface the most specific known cause in priority order: a malformed result
+    // (file existed but never parsed) > a non-ENOENT read failure > bare timeout.
+    const cause = lastParseError
+        ? `result never parsed (last error: ${lastParseError})`
+        : lastReadError
+            ? `result file unreadable (last error: ${lastReadError})`
+            : undefined;
+    const detail = cause ? `helper ${command} ${cause}` : `helper ${command} timed out`;
+    await opts.log?.(`signed helper ${command} timed out after ${timeoutMs}ms${cause ? ` — ${cause}` : ""}`);
+    return { ok: false, status: "timeout", detail, unavailable: false };
+}
+/** Promise-based sleep (no deps). */
+function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+// ── public entry points ───────────────────────────────────────────────────────
+/**
+ * Pop the NATIVE macOS notification Allow/Deny dialog for the SIGNED GoCode
+ * helper (the first time), or resolve to the persisted decision on later runs.
+ * Returns the parsed {@link HelperResult}; `granted:true` / `status:"authorized"`
+ * means the user allowed (or had already allowed) GoCode desktop notifications.
+ *
+ * On a machine where the signed bundle isn't available (non-macOS, or a publish
+ * that didn't ship it) this resolves to `{ unavailable:true }` so the caller can
+ * fall back to the legacy applet + "open Settings" nudge.
+ */
+export async function requestMacPermission(opts = {}, versionTag = VERSION) {
+    // Give the dialog a generous window: the user has to read + click.
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_HELPER_TIMEOUT_MS;
+    return runHelper("request-permission", ["--timeout", String(Math.floor(timeoutMs / 1000))], opts, versionTag);
+}
+/** Read the current authorization status without prompting (read-only). */
+export async function macHelperStatus(opts = {}, versionTag = VERSION) {
+    return runHelper("status", [], opts, versionTag);
+}
+/**
+ * Post ONE first-class UserNotifications banner via the SIGNED helper (attributed
+ * to the authorized "GoCode" app, with a real click action). Falls back to
+ * `{ unavailable:true }` when the signed bundle isn't usable, so the caller can
+ * use the legacy applet path instead.
+ */
+export async function notifyViaMacHelper(input, opts = {}, versionTag = VERSION) {
+    const args = [
+        "--title", input.title,
+        "--body", input.body,
+        "--sound", input.sound ? "1" : "0",
+    ];
+    if (input.clickApp && input.clickPath) {
+        args.push("--click-app", input.clickApp, "--click-path", input.clickPath);
+    }
+    return runHelper("notify", args, opts, versionTag);
+}