@trygocode/notify 0.5.0 → 0.6.0

package/README.md

@@ -529,6 +529,34 @@ npm publish, real-device E2E), see
 
 ## Changelog
 
+### 0.6.0
+
+- **Real native macOS "Allow Notifications" dialog (signed helper).** GoCode now
+  ships a tiny **Developer-ID-signed** macOS app bundle (`GoCodeNotifier.app`,
+  Team `88DC7KFY7M`) inside the package. On macOS, `gocode-notify permissions`
+  (and the post-`setup` nudge) now pop the **real system Allow/Don't-Allow
+  permission modal** — the thing a plain `npx`/`osascript` helper can't do —
+  instead of only opening System Settings and asking you to hunt for the toggle.
+  Once allowed, desktop banners post as a **first-class, authorized** app
+  (proper attribution + a real click-to-open-your-IDE action).
+  - **How it ships:** the bundle is **pre-signed at build time** by the
+    maintainer (`native/macos/build_and_sign.sh`) and committed to `assets/`, so
+    end-users need **no Xcode, no Developer ID, no compile step** — the one-line
+    install is unchanged. The signature survives the npm pack/extract round-trip.
+  - **Two macOS rules it honors (both required for the dialog to appear):** the
+    helper is copied to a **stable** location (`~/.gocode/desktop/`) — never
+    `/tmp` — and is always launched via **LaunchServices** (`open`), never by
+    exec'ing the inner binary (direct-exec auto-denies and the denial sticks).
+  - **Hot-path stays fast:** fire-and-forget banners read a cached auth status
+    (`~/.gocode/desktop/.auth-status`), so a notification never does a slow live
+    permission round-trip. The signed banner is used only once you've granted;
+    otherwise it transparently falls back to the legacy applet banner.
+  - **Own identity:** the signed helper uses bundle id `com.gocode.notify.helper`
+    (distinct from the legacy applet's `com.gocode.notify.desktop`) so it owns
+    its own row in System Settings → Notifications.
+  - **Linux/Windows unchanged.** This is a macOS-only enhancement; other
+    platforms keep their existing branded-banner paths.
+
 ### 0.5.0
 
 - **Question detection across ALL IDEs — "Agent needs you" vs "finished".** When

package/assets/GoCodeNotifier.app/Contents/Info.plist

@@ -0,0 +1,37 @@
+<?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">
+<dict>
+  <!-- CFBundleIdentifier MUST stay stable across rebuilds: macOS keys the user's
+       notification-authorization grant off it, so changing it would forget the
+       Allow. This is DISTINCT from the legacy applet's `com.gocode.notify.desktop`
+       on purpose: the signed helper owns its own identity in System Settings →
+       Notifications so a poisoned/denied state on the old shared id can't block
+       the signed app's grant. Mirrors HELPER_BUNDLE_ID in mac_helper.ts. -->
+  <key>CFBundleIdentifier</key>
+  <string>com.gocode.notify.helper</string>
+  <key>CFBundleName</key>
+  <string>GoCode</string>
+  <key>CFBundleDisplayName</key>
+  <string>GoCode</string>
+  <key>CFBundleExecutable</key>
+  <string>GoCodeNotifier</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleShortVersionString</key>
+  <string>1.0.0</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <!-- LSUIElement: a faceless background helper — no Dock icon, no menu bar. -->
+  <key>LSUIElement</key>
+  <true/>
+  <key>LSMinimumSystemVersion</key>
+  <string>11.0</string>
+  <key>CFBundleIconFile</key>
+  <string>AppIcon</string>
+  <key>NSHumanReadableCopyright</key>
+  <string>© BIGSMS Pty Ltd</string>
+</dict>
+</plist>

package/assets/GoCodeNotifier.app/Contents/_CodeSignature/CodeResources

@@ -0,0 +1,128 @@
+<?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">
+<dict>
+	<key>files</key>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<data>
+		GbhU1RfeSzs8A7x841vrx8S9NpM=
+		</data>
+	</dict>
+	<key>files2</key>
+	<dict>
+		<key>Resources/AppIcon.icns</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			80/V6KfdsY5g+nVZNtqimRwukW+CXDnk+bV0NlYa75w=
+			</data>
+		</dict>
+	</dict>
+	<key>rules</key>
+	<dict>
+		<key>^Resources/</key>
+		<true/>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^version.plist$</key>
+		<true/>
+	</dict>
+	<key>rules2</key>
+	<dict>
+		<key>.*\.dSYM($|/)</key>
+		<dict>
+			<key>weight</key>
+			<real>11</real>
+		</dict>
+		<key>^(.*/)?\.DS_Store$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>2000</real>
+		</dict>
+		<key>^(Frameworks|SharedFrameworks|PlugIns|Plug-ins|XPCServices|Helpers|MacOS|Library/(Automator|Spotlight|LoginItems))/</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^.*</key>
+		<true/>
+		<key>^Info\.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^PkgInfo$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^[^/]+$</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^embedded\.provisionprofile$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^version\.plist$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+	</dict>
+</dict>
+</plist>

package/dist/src/cli.js

@@ -21,7 +21,7 @@ import { setup } from "./setup.js";
 import { uninstall } from "./uninstall.js";
 import { cmdConfig } from "./config.js";
 import { onStop } from "./on_stop.js";
-import { notifyDesktop } from "./desktop_notify.js";
+import { notifyDesktop, requestDesktopPermission } from "./desktop_notify.js";
 import { gatherDoctor, formatDoctor } from "./doctor.js";
 /** Subcommands the finished CLI will expose (see PRD §4.1). */
 export const COMMANDS = [
@@ -31,6 +31,7 @@ export const COMMANDS = [
     "setup",
     "status",
     "doctor",
+    "permissions",
     "mcp",
     "uninstall",
     "config",
@@ -93,6 +94,7 @@ export function printHelp() {
         "  setup      Pair + detect runtimes + write configs",
         "  status     Report credentials / server / detected runtimes",
         "  doctor     Self-diagnostic checklist with exact fix commands",
+        "  permissions  Request macOS desktop-notification permission (opens Settings)",
         "  mcp        Run as an MCP server over stdio",
         "  uninstall  Remove entries this tool added",
         "  config     Get/set Notify settings (get | set <key> <value> | pull)",
@@ -366,6 +368,48 @@ export async function cmdTest(args, deps = {}) {
         console.error(`gocode-notify test: ${detail}.`);
     return 1;
 }
+/**
+ * Handle `gocode-notify permissions` (alias `perms`). Makes the OS
+ * notification-permission UI appear so the user grants GoCode desktop banners
+ * with a click instead of hunting through Settings.
+ *
+ * On macOS this now pops the REAL native Allow/Deny modal via the Developer-ID-
+ * signed helper bundled in the package (see {@link requestDesktopPermission}); if
+ * the signed helper is unavailable or you previously denied, it falls back to
+ * registering the branded bundle, opening System Settings → Notifications, and
+ * firing a priming banner. Always exits 0 — best-effort convenience, never a gate.
+ */
+export async function cmdPermissions(args, deps = {}) {
+    const flags = parseFlags(args);
+    const agent = isAgentDriven(flags);
+    const sink = deps.sink ?? stdoutSink;
+    const res = await requestDesktopPermission({
+        home: deps.home,
+        timeoutMs: deps.timeoutMs,
+        timestamp: deps.timestamp,
+    });
+    if (agent) {
+        // `ok` reflects whether the NOTIFICATION path actually worked (the priming
+        // banner fired) — NOT merely that we opened Settings. On macOS, opening
+        // Settings is only a partial remediation; reporting ok:true off it alone
+        // would be false-success telemetry for automation consuming the sink.
+        sink({
+            step: "permissions",
+            ok: res.primed,
+            detail: res.message,
+        });
+    }
+    else {
+        console.log(`🔔 ${res.message}`);
+        if (res.platform === "darwin" && !res.primed) {
+            // Only show the Settings-hunt hint when we did NOT manage a real grant
+            // (e.g. previously denied, or the signed helper wasn't available).
+            console.log("   (If no dialog appeared, enable “Allow Notifications” for GoCode in\n" +
+                "    System Settings → Notifications — it’s now one tap away.)");
+        }
+    }
+    return 0;
+}
 /**
  * Handle `gocode-notify status [--server URL]`. Prints a coherent report of
  * credentials / server reachability / detected runtimes (PRD §4.1, §8). Purely
@@ -462,6 +506,28 @@ export async function cmdSetup(args, deps = {}) {
             console.log(`  ${step.ok ? "✓" : "✗"} ${step.step}: ${step.detail}`);
         }
     }
+    // On macOS, proactively trigger the notification-permission flow so the user
+    // doesn't have to hunt for the GoCode toggle: register the branded bundle,
+    // open System Settings → Notifications, and fire a priming banner. Skipped in
+    // agent-driven mode (no human to grant it) and when setup didn't succeed.
+    // Best-effort — never flips the setup exit code (a permission nudge failing
+    // must not make `setup` report failure).
+    if (!agent && result.ok && process.platform === "darwin") {
+        try {
+            const perm = await requestDesktopPermission({
+                home: deps.home,
+                timeoutMs: deps.timeoutMs,
+            });
+            console.log("");
+            console.log(`  🔔 Desktop notifications: ${perm.message}`);
+        }
+        catch (err) {
+            // Never let a permission nudge fail the setup — but DO leave a breadcrumb
+            // so an unexpected throw here isn't completely invisible to the user.
+            console.log("");
+            console.log(`  🔔 Desktop notifications: couldn't run the permission nudge (${err instanceof Error ? err.message : String(err)}). Run \`gocode-notify permissions\` manually.`);
+        }
+    }
     return result.ok ? 0 : 1;
 }
 /**
@@ -689,6 +755,8 @@ export async function runAsync(argv) {
         return cmdStatus(argv.slice(1));
     if (cmd === "doctor")
         return cmdDoctor(argv.slice(1));
+    if (cmd === "permissions" || cmd === "perms")
+        return cmdPermissions(argv.slice(1));
     if (cmd === "setup")
         return cmdSetup(argv.slice(1));
     if (cmd === "mcp")

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);
+}

package/dist/src/send.js

@@ -32,8 +32,25 @@ export const NOTIFY_KINDS = [
 export function isNotifyKind(value) {
     return typeof value === "string" && NOTIFY_KINDS.includes(value);
 }
-/** Default request timeout (PRD §4.4: 5s hard cap). */
-export const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * Default PER-ATTEMPT request timeout. Bumped 5s → 12s (2026-06-20): a cold
+ * self-hosted OpenHands server reached over Tailscale routinely takes 5-8s to
+ * answer its first request after idle, so the old 5s cap silently dropped real
+ * `finished` / `awaiting_input` pushes (observed in `notify.log`:
+ * "timeout after 5000ms"). 12s comfortably clears a cold-start round-trip while
+ * still being a hard cap so a wedged server can never hang a hook's turn.
+ */
+export const DEFAULT_TIMEOUT_MS = 12000;
+/**
+ * How many times to ATTEMPT a send before giving up (1 = no retry). A single
+ * cold-start timeout or transient network blip used to mean the user got no
+ * notification at all; we now retry transient failures (timeout / network /
+ * 5xx) with a short backoff so a slow-but-reachable server still delivers.
+ * A 4xx (auth / bad request) is permanent and is NOT retried.
+ */
+export const DEFAULT_MAX_ATTEMPTS = 3;
+/** Backoff (ms) applied BEFORE attempt N (index 0 = before the 2nd attempt). */
+export const RETRY_BACKOFF_MS = [500, 1500];
 /** Rotate `notify.log` once it grows past this (keeps one `.1` backup). */
 export const MAX_LOG_BYTES = 256 * 1024;
 /** Absolute path to the failure log. */
@@ -93,13 +110,32 @@ async function failure(reason, opts, extra = {}) {
     await appendLog(`SEND FAIL: ${reason}`, opts);
     return { ok: false, error: reason, ...extra };
 }
+/** Real backoff sleep (cancellable-free; the caller never aborts a backoff). */
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /**
- * Send one push to `/notify/send`. Resolves (never rejects) to a
- * {@link SendResult}; callers may treat ANY result as "exit 0".
+ * Send one push to `/notify/send`, retrying transient failures with a short
+ * backoff. Resolves (never rejects) to a {@link SendResult}; callers may treat
+ * ANY result as "exit 0".
+ *
+ * Retry policy (2026-06-20): a single cold-start timeout or transient network
+ * blip used to drop the user's notification entirely. We now attempt up to
+ * {@link DEFAULT_MAX_ATTEMPTS} times, backing off per {@link RETRY_BACKOFF_MS}
+ * between attempts. A 4xx (auth / bad-request) is PERMANENT and stops the loop
+ * immediately — retrying it would just burn the hook's time budget. Every
+ * attempt's failure is logged so `notify.log` shows the full retry trail.
  */
 export async function send(payload, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    // Coerce defensively: a NaN (e.g. a failed CLI numeric parse) must not make
+    // `Math.max(1, NaN) === NaN` skip the loop and then throw on `last!.result`.
+    const rawAttempts = opts.maxAttempts;
+    const maxAttempts = typeof rawAttempts === "number" && Number.isFinite(rawAttempts)
+        ? Math.max(1, Math.floor(rawAttempts))
+        : DEFAULT_MAX_ATTEMPTS;
+    const sleep = opts.sleepImpl ?? defaultSleep;
     let creds;
     try {
         creds = await readCredentials(opts);
@@ -112,41 +148,78 @@ export async function send(payload, opts = {}) {
     }
     const server = normalizeServer(opts.server ?? creds.server ?? builtinDefaultServer());
     const url = `${server}/api/v1/notify/send`;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const res = await fetchImpl(url, {
-            method: "POST",
-            headers: {
-                "content-type": "application/json",
-                authorization: `Bearer ${creds.api_key}`,
-            },
-            body: JSON.stringify(buildBody(payload)),
-            signal: controller.signal,
-        });
-        if (!res.ok) {
-            return failure(`server responded ${res.status} for kind=${payload.kind}`, opts, {
-                status: res.status,
+    const apiKey = creds.api_key;
+    const body = JSON.stringify(buildBody(payload));
+    /** One attempt — resolves to an {@link AttemptOutcome}, never throws. */
+    const attempt = async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${apiKey}`,
+                },
+                body,
+                signal: controller.signal,
             });
+            if (!res.ok) {
+                // 5xx is transient (server hiccup / cold start) → retriable.
+                // 4xx is permanent (auth / bad request) → do not retry.
+                const retriable = res.status >= 500;
+                return {
+                    result: { ok: false, status: res.status, error: `server responded ${res.status} for kind=${payload.kind}` },
+                    retriable,
+                };
+            }
+            let sent;
+            try {
+                const json = (await res.json());
+                if (typeof json?.sent === "number")
+                    sent = json.sent;
+            }
+            catch {
+                // A 2xx with an unparseable body still counts as delivered.
+            }
+            return { result: { ok: true, status: res.status, sent }, retriable: false };
         }
-        let sent;
-        try {
-            const json = (await res.json());
-            if (typeof json?.sent === "number")
-                sent = json.sent;
+        catch (err) {
+            // Timeout (aborted) and network errors are both transient → retriable.
+            const reason = controller.signal.aborted
+                ? `timeout after ${timeoutMs}ms for kind=${payload.kind}`
+                : `request failed: ${errMessage(err)}`;
+            return { result: { ok: false, error: reason }, retriable: true };
         }
-        catch {
-            // A 2xx with an unparseable body still counts as delivered.
+        finally {
+            clearTimeout(timer);
         }
-        return { ok: true, status: res.status, sent };
-    }
-    catch (err) {
-        const reason = controller.signal.aborted
-            ? `timeout after ${timeoutMs}ms for kind=${payload.kind}`
-            : `request failed: ${errMessage(err)}`;
-        return failure(reason, opts);
-    }
-    finally {
-        clearTimeout(timer);
+    };
+    let last;
+    for (let i = 0; i < maxAttempts; i++) {
+        if (i > 0) {
+            // Backoff before this retry. Clamp to the last defined step for any
+            // attempt count beyond the table so a larger `maxAttempts` still works.
+            const backoff = RETRY_BACKOFF_MS[Math.min(i - 1, RETRY_BACKOFF_MS.length - 1)] ?? 0;
+            await sleep(backoff);
+        }
+        last = await attempt();
+        if (last.result.ok) {
+            // Note the recovery in the log when an earlier attempt had failed, so a
+            // "it worked on retry 2" story is visible in notify.log.
+            if (i > 0) {
+                await appendLog(`SEND OK on attempt ${i + 1}/${maxAttempts} for kind=${payload.kind}`, opts);
+            }
+            return last.result;
+        }
+        // Log every failed attempt so the retry trail is diagnosable.
+        const willRetry = last.retriable && i < maxAttempts - 1;
+        await appendLog(`SEND FAIL (attempt ${i + 1}/${maxAttempts}${willRetry ? ", will retry" : ""}): ${last.result.error}`, opts);
+        // Permanent failure (4xx) — stop immediately, retrying can't help.
+        if (!last.retriable)
+            break;
     }
+    // All attempts exhausted (or a permanent failure). `last` is always set here
+    // because the loop runs at least once (maxAttempts >= 1).
+    return last.result;
 }

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Single source of truth for the CLI version. Keep in sync with package.json.
-export const VERSION = "0.5.0";
+export const VERSION = "0.6.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trygocode/notify",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Free phone + branded desktop notifications for any coding agent (Cursor, Claude Code, OpenCode, Ralph/Homer) via the GoCode app.",
   "license": "MIT",
   "type": "module",