@trygocode/notify 0.3.4 → 0.4.0

package/README.md

@@ -1,12 +1,14 @@
 # @trygocode/notify
 
-Free phone notifications for any coding agent — **Cursor, Claude Code, OpenCode,
-or any Ralph/Homer loop** — delivered to your phone via the
-[GoCode](https://oh.jeltechsolutions.com) app + FCM.
+Free phone **and branded desktop** notifications for any coding agent — **Cursor,
+Claude Code, OpenCode, or any Ralph/Homer loop** — delivered to your phone via the
+[GoCode](https://oh.jeltechsolutions.com) app + FCM, and to your computer as a
+native **"GoCode"** banner.
 
-You get an automatic push when your agent **finishes a turn**, **goes idle
+You get an automatic notification when your agent **finishes a turn**, **goes idle
 waiting for you**, **errors out**, or when an overnight **loop completes / halts**
-— so you can walk away and let your phone tell you when it needs you.
+— on your phone AND on the computer you're working on (on by default) — so you can
+walk away and let either device tell you when it needs you.
 
 ## Contents
 
@@ -157,6 +159,69 @@ never get double-pinged.
 > `setup`/`setup --force`. `send` and `test` remain callable on their own for
 > scripts and power users.
 
+## Desktop notifications (branded, on by default)
+
+GoCode Notify also raises a **real, branded "GoCode" banner on the computer you're
+working on** — the same instant your phone gets pinged — so you're told whether
+you're at your desk or away. It's **ON by default** once the package is installed
+and is controlled by the **same server-synced settings** as the phone push, so a
+toggle in the app or the terminal flips the computer banner everywhere.
+
+**Word-for-word identical to the phone.** The banner reads exactly the same as the
+push you'd get on your phone — same status emoji, IDE/source label, project, and
+per-kind copy (e.g. `✅ Cursor · openhandapp — Agent finished`). The wording is a
+faithful mirror of the server's notification decoration and the Flutter client's,
+pinned by a cross-check test (`notify_copy.test.ts`) so the three surfaces can't
+drift.
+
+**Click to open your IDE (macOS).** Clicking the banner opens the **IDE window for
+that project** — the same editor that raised the turn (Cursor / VS Code), focused
+on the project you were working in. This is best-effort: when the IDE/project
+can't be named the banner is simply display-only (never a dead or mis-routed
+click). It opens the project *window*, not a specific past chat — IDEs don't
+expose reliable per-chat deep links.
+
+| OS | How it's shown | Branded as |
+|---|---|---|
+| **macOS** | A one-time `osacompile`d `GoCode.app` helper under `~/.gocode/desktop/` raises the banner via the system | **"GoCode"** + the GoCode icon |
+| **Windows** | A WinRT `ToastGeneric` toast bound to a one-time Start-Menu shortcut carrying the `GoCode.Notify` AppUserModelID | **"GoCode"** |
+| **Linux** | `notify-send -a GoCode -i <icon>` | **"GoCode"** + icon |
+
+**Zero new dependencies.** It uses only tools that ship with the OS (`osacompile`/
+`osascript`/`sips` on macOS, PowerShell + WinRT on Windows, `notify-send` on Linux)
+— so the **one-line install does not change at all**. The first banner builds a tiny
+branded helper once and caches it; every banner after that just fires it.
+
+### Control it
+
+From the **GoCode app** (Settings → **GoCode Notify** → *Desktop notifications*),
+or from the terminal:
+
+```bash
+gocode-notify config set desktop.enabled false   # silence the computer banner
+gocode-notify config set desktop.sound   false   # keep the banner, drop the sound
+```
+
+The phone push is unaffected — `desktop.*` only governs the local banner.
+
+### Try it right now
+
+```bash
+# Fire a branded test banner on THIS computer (independent of the phone push):
+gocode-notify test --desktop
+```
+
+You should see a **"GoCode"** notification appear on your screen. On a headless
+box / CI / SSH session where a banner makes no sense, set
+`GOCODE_NOTIFY_NO_DESKTOP=1` to hard-disable local banners for that machine.
+
+> **macOS branding note.** A bare `osascript` banner is attributed to "Script
+> Editor". To brand it "GoCode", the package compiles a minimal AppleScript app
+> bundle (`~/.gocode/desktop/GoCode.app`) once with `osacompile` (ships with
+> every Mac — no Xcode/Swift) and drops the GoCode icon into it via `sips`. If
+> that one-time setup ever fails, the banner still fires (unbranded) rather than
+> blocking your turn.
+
 ## Hand off to your server — `launch` / `autopilot`
 
 > **New in 0.2.0.** Notify can now do more than ping your phone — it can **hand a
@@ -344,6 +409,8 @@ Valid keys (mirror of the canonical schema):
 | `commit_message.mode` | `auto` \| `ai` \| `deterministic` | Commit-message strategy |
 | `commit_message.command` | string \| null | Explicit local summariser command |
 | `commit_message.max_diff_bytes` | int > 0 | Diff byte cap fed to the summariser (default 61440) |
+| `desktop.enabled` | bool | Branded desktop banner on this computer (**ON by default**) |
+| `desktop.sound` | bool | Play a sound with the desktop banner (default true) |
 
 ```bash
 # Examples
@@ -440,6 +507,34 @@ npm publish, real-device E2E), see
 
 ## Changelog
 
+### 0.4.0
+
+- **New: branded desktop notifications (on by default).** Every event that pings
+  your phone now also raises a native, **GoCode-branded** banner on the computer
+  you're working on — macOS (a one-time `osacompile`d `GoCode.app` helper +
+  `sips` icon), Windows (a WinRT `ToastGeneric` toast bound to a one-time
+  Start-Menu shortcut with the `GoCode.Notify` AppUserModelID), and Linux
+  (`notify-send -a GoCode`). **Zero new dependencies** — OS-native tools only,
+  so the one-line install is unchanged. Controlled by the same server-synced
+  settings as the phone push via the new `desktop.enabled` / `desktop.sound`
+  keys (both default ON); toggle from the app or `gocode-notify config set
+  desktop.enabled false`. Try it with `gocode-notify test --desktop`. Hard-
+  disable per machine with `GOCODE_NOTIFY_NO_DESKTOP=1` (headless / CI / SSH).
+  Best-effort + non-blocking: a failed banner never blocks or fails your turn.
+- **Word-for-word match with the phone push.** The desktop banner now reads
+  EXACTLY like the phone notification — same status emoji + IDE/source label +
+  project + per-kind title/body (e.g. `✅ Cursor · openhandapp — Agent
+  finished`). New `src/notify_copy.ts` mirrors the server's `_decorated_title` /
+  `_decorated_body` + `_DEFAULT_TITLES` / `_DEFAULT_BODIES` and the Flutter
+  client's `decorateNotificationTitle` / `sourceLabelFor`, pinned by a
+  cross-check test so the CLI/server/app surfaces can't drift.
+- **Click to open the IDE window for the project (macOS).** Clicking the banner
+  opens the IDE that raised the turn (Cursor / VS Code) focused on the project
+  directory. Implemented zero-dependency: the branded AppleScript applet handles
+  the click re-run (documented macOS behaviour) and `open -a <ide> <project>`.
+  Best-effort — display-only when the IDE/project can't be named. Opens the
+  project *window*, not a specific chat (IDEs lack reliable per-chat deep links).
+
 ### 0.3.0
 
 - **New: Cursor `stop.status` → kind mapping (T-CUR1/T-CUR4).** The `on-stop`
@@ -510,6 +605,9 @@ Zero runtime dependencies beyond the MCP SDK (Node built-in `fetch`/`fs`/
 | `src/setup.ts` | Installer orchestration (pair → detect → write configs) |
 | `src/claude.ts` / `src/cursor.ts` / `src/opencode.ts` | Per-client config writers (hooks + MCP + rule/skill); hooks call the `on-stop` dispatcher. OpenCode uses a `session.idle` plugin instead of a hooks file |
 | `src/send.ts` / `src/login.ts` / `src/mcp.ts` | Core send, pairing, and MCP server (incl. `gocode_launch_autopilot`) |
+| `src/desktop_notify.ts` | Branded native desktop banners (macOS `GoCode.app` / Windows WinRT toast / Linux `notify-send`); zero-dep, best-effort; macOS click-through opens the IDE window |
+| `src/notify_copy.ts` | Banner wording mirror — reproduces the server/Flutter title/body decoration so the desktop banner reads word-for-word like the phone |
+| `assets/gocode-icon.{png,ico}` | Bundled GoCode icon used to brand desktop banners |
 | `src/launch.ts` | Shared `launch()` core behind the `launch`/`autopilot` command + the MCP tool |
 | `src/push.ts` | Auto-push flow behind the `on-stop` dispatcher — git add/commit/push, FF-only |
 | `src/commit_message.ts` | AI commit-message resolution chain + deterministic fallback |

package/dist/src/cli.js

@@ -21,6 +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 { gatherDoctor, formatDoctor } from "./doctor.js";
 /** Subcommands the finished CLI will expose (see PRD §4.1). */
 export const COMMANDS = [
@@ -88,7 +89,7 @@ export function printHelp() {
         "Commands:",
         "  login      Pair this machine with your GoCode account",
         "  send       Send a single push notification",
-        "  test       Send a canned test push",
+        "  test       Send a canned test push (add --desktop for a local banner)",
         "  setup      Pair + detect runtimes + write configs",
         "  status     Report credentials / server / detected runtimes",
         "  doctor     Self-diagnostic checklist with exact fix commands",
@@ -313,6 +314,32 @@ export async function cmdTest(args, deps = {}) {
     const flags = parseFlags(args);
     const agent = isAgentDriven(flags);
     const sink = deps.sink ?? stdoutSink;
+    // `--desktop`: fire a BRANDED local desktop banner so the user can verify the
+    // computer-notification path (and its GoCode branding) works during install,
+    // independent of the phone push (GOCODE_NOTIFY_DESKTOP PRD §3). Unlike the
+    // fire-and-forget hook path, this interactive probe reports the real outcome
+    // and exits non-zero on failure so the human/agent sees it.
+    if (flagBool(flags, "desktop")) {
+        const desk = await notifyDesktop({
+            title: "GoCode test",
+            body: "If you can read this banner, GoCode desktop notifications work.",
+            kind: "finished",
+            sound: true,
+        }, { home: deps.home, timeoutMs: deps.timeoutMs, timestamp: deps.timestamp });
+        if (desk.ok) {
+            if (agent)
+                sink({ step: "test-desktop", ok: true, detail: `desktop banner shown (${desk.platform})` });
+            else
+                console.log(`✓ Desktop banner shown (${desk.platform}). Look for the GoCode notification on your screen.`);
+            return 0;
+        }
+        const detail = `desktop banner not shown (${desk.error ?? "unknown"})`;
+        if (agent)
+            sink({ step: "test-desktop", ok: false, detail });
+        else
+            console.error(`gocode-notify test --desktop: ${detail}.`);
+        return 1;
+    }
     const server = await resolveServerUrl(flagString(flags, "server"), deps);
     const sendOpts = {
         home: deps.home,

package/dist/src/desktop_notify.js

@@ -0,0 +1,584 @@
+// `desktop_notify` — BRANDED native desktop notifications on the dev machine
+// (GOCODE_NOTIFY_DESKTOP PRD §2). The companion to the phone push: when the
+// agent finishes a turn / errors / a loop completes, the SAME event that pings
+// your phone via FCM also raises a real OS banner on the computer you're sitting
+// at — so you get told whether you're at your desk or away.
+//
+// SCOPE OF THIS MODULE: take a resolved {title, body, kind, sound} and raise ONE
+// native banner on whatever OS we're on, BRANDED as "GoCode" with the GoCode
+// icon. It owns the per-platform mechanics + the one-time branding setup; the
+// DECISION of whether to fire (settings gating) lives in `on_stop.ts` / the CLI,
+// exactly like the phone `send` path.
+//
+// Contract (mirrors `send.ts` — PRD §0.5 "Never block the agent"):
+//   - Hard timeout (default 5s) — a wedged osascript/PowerShell can never hang a
+//     hook's turn. Best-effort: NEVER throws, NEVER rejects; always resolves to a
+//     {@link DesktopResult}. A failed banner must never block or fail the agent.
+//   - Failures are appended to `~/.gocode/notify.log` (shared with the sender).
+//
+// BRANDING — the whole point of this module (zero new npm deps, OS tools only):
+//   • macOS  → we `osacompile` a tiny "GoCode.app" AppleScript bundle ONCE into
+//     `~/.gocode/desktop/GoCode.app`, drop the bundled GoCode `.icns`/PNG into
+//     it, and invoke its `applet` binary. macOS attributes the banner to the
+//     SENDING app bundle, so the notification shows "GoCode" + our icon (a bare
+//     `osascript display notification` would show "Script Editor"). `osacompile`
+//     ships with every macOS — no Xcode, no Swift, no Homebrew.
+//   • Windows → we ensure a Start-Menu `.lnk` shortcut carrying our
+//     AppUserModelID ("GoCode.Notify") exists ONCE, then raise a WinRT
+//     `ToastGeneric` toast bound to that AUMID via inline PowerShell. Windows
+//     keys the toast's app name + icon off the AUMID's shortcut, so the toast
+//     reads "GoCode". PowerShell + WinRT ship with Windows 10/11 — no deps.
+//   • Linux  → `notify-send -a GoCode -i <icon>` (the `-a` app-name + `-i` icon
+//     flags brand it). libnotify is present on essentially every desktop distro.
+//
+// Zero runtime deps — Node built-ins only (child_process / fs / os / path / url),
+// matching the package's zero-dependency rule.
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendLog } from "./send.js";
+import { gocodeDir } from "./creds.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). */
+export const WINDOWS_AUMID = "GoCode.Notify";
+/** The app/bundle display name every platform brands the banner with. */
+export const APP_NAME = "GoCode";
+/**
+ * Version of the compiled macOS helper bundle. BUMP this whenever the applet's
+ * 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.
+ */
+export const MAC_BUNDLE_VERSION = 2;
+/**
+ * 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
+ * a native banner makes no sense. Treated as truthy for any value other than the
+ * usual falsy strings. Checked first thing in {@link notifyDesktop} so it can
+ * never spawn a banner process. (The test suite also sets it so unit tests never
+ * raise real OS banners.)
+ */
+export const DISABLE_DESKTOP_ENV = "GOCODE_NOTIFY_NO_DESKTOP";
+/** True when {@link DISABLE_DESKTOP_ENV} is set to a truthy value. */
+export function desktopDisabledByEnv(env = process.env) {
+    const raw = env[DISABLE_DESKTOP_ENV];
+    if (raw == null)
+        return false;
+    const v = raw.trim().toLowerCase();
+    return v !== "" && v !== "0" && v !== "false" && v !== "no" && v !== "off";
+}
+/**
+ * Default OS-command runner: spawn `cmd args`, optionally feed `input` on stdin,
+ * capture stdout/stderr, and resolve with the exit code. NEVER rejects — a spawn
+ * error (binary missing) resolves to a non-zero code so the flow treats it as a
+ * skip, not a throw. A hard timeout kills a wedged child so a hook never hangs.
+ */
+export const defaultRunner = (cmd, args, opts) => new Promise((resolve) => {
+    let settled = false;
+    const finish = (r) => {
+        if (settled)
+            return;
+        settled = true;
+        resolve(r);
+    };
+    let child;
+    try {
+        child = spawn(cmd, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+            env: opts.env ? { ...process.env, ...opts.env } : process.env,
+        });
+    }
+    catch (err) {
+        finish({ code: 127, stdout: "", stderr: String(err) });
+        return;
+    }
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (c) => (stdout += c));
+    child.stderr?.on("data", (c) => (stderr += c));
+    const timer = setTimeout(() => {
+        try {
+            child.kill("SIGKILL");
+        }
+        catch {
+            // ignore
+        }
+        finish({ code: 124, stdout, stderr: stderr || "timeout" });
+    }, opts.timeoutMs);
+    child.on("error", (err) => {
+        clearTimeout(timer);
+        finish({ code: 127, stdout, stderr: stderr || String(err) });
+    });
+    child.on("close", (code) => {
+        clearTimeout(timer);
+        finish({ code: code ?? 1, stdout, stderr });
+    });
+    if (opts.input !== undefined) {
+        try {
+            child.stdin?.end(opts.input);
+        }
+        catch {
+            // a broken pipe must not throw
+        }
+    }
+    else {
+        try {
+            child.stdin?.end();
+        }
+        catch {
+            // ignore
+        }
+    }
+});
+/** Directory under `~/.gocode/` holding the branding helper (the .app / marker). */
+export function desktopDir(opts) {
+    return path.join(gocodeDir(opts), "desktop");
+}
+/**
+ * Resolve the bundled GoCode icon shipped in the package's `assets/` dir. The
+ * compiled module lives at `dist/src/desktop_notify.js`, so `assets/` is two
+ * levels up (`dist/src/.. /.. /assets`). Returns the platform-appropriate file
+ * (PNG everywhere; `.ico` is only meaningful to Windows but we ship PNG too).
+ * Returns undefined when the asset can't be located (then we brand by name only).
+ */
+export function bundledIconPath(ext = "png") {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url)); // dist/src
+        const candidate = path.resolve(here, "..", "..", "assets", `gocode-icon.${ext}`);
+        return candidate;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Escape a string for safe embedding inside an AppleScript double-quoted literal. */
+export function escapeAppleScript(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/** Escape a string for safe embedding inside a PowerShell single-quoted literal. */
+export function escapePowerShellSingleQuoted(s) {
+    return s.replace(/'/g, "''");
+}
+/** Escape text for safe embedding inside toast XML (the 5 XML entities). */
+export function escapeXml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * Raise ONE branded native desktop banner for `payload`. Best-effort + total:
+ * NEVER throws, NEVER rejects; always resolves to a {@link DesktopResult}, and
+ * the caller can treat any result as "exit 0". Branding setup is one-time and
+ * cached; if it fails the banner still fires unbranded (degrade, never block).
+ */
+export async function notifyDesktop(payload, opts = {}) {
+    const platform = (opts.platform ?? process.platform);
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_DESKTOP_TIMEOUT_MS;
+    const run = opts.run ?? defaultRunner;
+    const logLine = async (line) => {
+        try {
+            if (opts.log)
+                await opts.log(line);
+            else
+                await appendLog(`DESKTOP: ${line}`, { home: opts.home, timestamp: opts.timestamp });
+        }
+        catch {
+            // logging must never block the flow
+        }
+    };
+    // Machine-level hard opt-out (headless / CI / SSH). Never spawn anything.
+    // Honour a per-call `opts.env` override too (consistency with the runner,
+    // which merges opts.env into the child env) — falling back to process.env.
+    if (desktopDisabledByEnv({ ...process.env, ...(opts.env ?? {}) })) {
+        await logLine(`disabled via ${DISABLE_DESKTOP_ENV} — skipped`);
+        return { ok: false, platform: "unsupported", error: `disabled via ${DISABLE_DESKTOP_ENV}` };
+    }
+    const title = (payload.title ?? APP_NAME).trim() || APP_NAME;
+    const body = (payload.body ?? "").trim();
+    const sound = payload.sound !== false; // default ON (PRD §2.1)
+    const click = payload.click;
+    try {
+        if (platform === "darwin") {
+            return await notifyMac({ title, body, sound, click }, { ...opts, run, timeoutMs, log: logLine });
+        }
+        if (platform === "win32") {
+            return await notifyWindows({ title, body, sound, click }, { ...opts, run, timeoutMs, log: logLine });
+        }
+        if (platform === "linux") {
+            return await notifyLinux({ title, body, sound, click }, { ...opts, run, timeoutMs, log: logLine });
+        }
+        await logLine(`no desktop banner path for platform "${platform}" — skipped`);
+        return { ok: false, platform: "unsupported", error: `unsupported platform ${platform}` };
+    }
+    catch (err) {
+        // Defence in depth: this module must never throw. Surface the real message
+        // (platform-specific integrations are fragile — keep the breadcrumb).
+        const msg = err instanceof Error ? err.message : String(err);
+        await logLine(`unexpected error on ${platform} — treated as no-op: ${msg}`);
+        return { ok: false, platform: "unsupported", error: `unexpected error: ${msg}` };
+    }
+}
+// ── macOS ────────────────────────────────────────────────────────────────────
+/** Path to the branded helper app bundle under `~/.gocode/desktop/GoCode.app`. */
+export function macAppPath(opts) {
+    return path.join(desktopDir(opts), "GoCode.app");
+}
+/**
+ * Path to the click-target state file the applet reads when a banner is clicked
+ * (PRD §3.6). Holds a single `"<app>\t<projectPath>"` line written just before
+ * the most recent banner is posted; the applet's click handler opens that IDE.
+ * Single-file (last-write-wins) is fine: the user clicks the banner they just
+ * saw, and a banner only stays clickable while it's the latest.
+ */
+export function macClickTargetPath(opts) {
+    return path.join(desktopDir(opts), "click-target.tsv");
+}
+/**
+ * Ensure the branded `GoCode.app` AppleScript bundle exists under
+ * `~/.gocode/desktop/`. Compiled ONCE with `osacompile` (ships with macOS), then
+ * the bundled GoCode icon is dropped in as `applet.icns` so the banner shows our
+ * icon + "GoCode". Idempotent: a second call no-ops when the bundle is present.
+ *
+ * The bundle's AppleScript reads the banner text from env vars
+ * (GOCODE_NOTIFY_TITLE / GOCODE_NOTIFY_MESSAGE / GOCODE_NOTIFY_SOUND) so we never
+ * recompile per banner — we just set env + invoke the `applet` binary directly
+ * (the only invocation that actually works headless; `open -a` silently no-ops
+ * for AppleScript applets).
+ *
+ * CLICK-THROUGH (PRD §3.6): clicking a banner posted by an AppleScript applet
+ * sends a fresh `run` event back to THIS applet (documented macOS behaviour). We
+ * distinguish the two run modes by the presence of GOCODE_NOTIFY_TITLE:
+ *   • env var SET   → we're posting a banner (the normal invoke).
+ *   • env var EMPTY → we were re-run by a notification CLICK → read the last
+ *     click-target file and `open -a <ide> <projectPath>` to focus the IDE.
+ * This keeps click-through ZERO-dependency (pure osacompile/AppleScript) — no
+ * Swift, no signed binary, no extra npm dep.
+ *
+ * Returns the applet binary path on success, or undefined when branding could
+ * not be set up (caller then falls back to a plain unbranded `osascript`).
+ */
+export async function ensureMacBrandedApp(ctx) {
+    const appPath = macAppPath(ctx);
+    const appletBin = path.join(appPath, "Contents", "MacOS", "applet");
+    const versionMarker = path.join(desktopDir(ctx), `.bundle-v${MAC_BUNDLE_VERSION}`);
+    try {
+        // Already built AND at the CURRENT bundle version? → reuse. The version
+        // marker lets a package update (e.g. adding the click handler) force a
+        // one-time recompile of a stale bundle from an older install.
+        await fs.access(appletBin);
+        await fs.access(versionMarker);
+        return appletBin;
+    }
+    catch {
+        // need to (re)build it — missing applet OR stale/absent version marker
+    }
+    try {
+        await fs.mkdir(desktopDir(ctx), { recursive: true, mode: 0o700 });
+        // The applet reads the banner text from the environment so we compile ONCE.
+        // The same applet handles a notification CLICK (a second `run` with NO env)
+        // by opening the IDE recorded in the click-target file (see header).
+        const clickFile = macClickTargetPath(ctx);
+        const script = [
+            'on run',
+            '  set theTitle to (system attribute "GOCODE_NOTIFY_TITLE")',
+            '  if theTitle is "" then',
+            '    -- No banner env → this run came from a notification CLICK. Open the',
+            '    -- IDE recorded by the last post (format: "<app>\\t<projectPath>").',
+            '    my handleClick()',
+            '    return',
+            '  end if',
+            '  set theMsg to (system attribute "GOCODE_NOTIFY_MESSAGE")',
+            '  set theSound to (system attribute "GOCODE_NOTIFY_SOUND")',
+            '  if theSound is "1" then',
+            '    display notification theMsg with title theTitle sound name "Glass"',
+            '  else',
+            '    display notification theMsg with title theTitle',
+            '  end if',
+            'end run',
+            '',
+            'on handleClick()',
+            '  try',
+            `    set p to "${escapeAppleScript(clickFile)}"`,
+            '    set f to POSIX file p',
+            '    set raw to (read f as «class utf8»)',
+            '    if raw is "" then return',
+            '    set AppleScript\'s text item delimiters to tab',
+            '    set parts to text items of raw',
+            '    set AppleScript\'s text item delimiters to ""',
+            '    if (count of parts) < 2 then return',
+            '    set ideApp to item 1 of parts',
+            '    set projPath to item 2 of parts',
+            '    -- strip any trailing newline from projPath',
+            '    if projPath ends with linefeed then set projPath to text 1 thru -2 of projPath',
+            '    if projPath ends with return then set projPath to text 1 thru -2 of projPath',
+            '    do shell script "open -a " & quoted form of ideApp & " " & quoted form of projPath',
+            '  end try',
+            'end handleClick',
+        ].join("\n");
+        const scptPath = path.join(desktopDir(ctx), "gocode-notify.applescript");
+        await fs.writeFile(scptPath, script, "utf8");
+        // Remove any stale/partial bundle so osacompile writes a clean one.
+        await fs.rm(appPath, { recursive: true, force: true }).catch(() => { });
+        const compiled = await ctx.run("osacompile", ["-o", appPath, scptPath], {
+            timeoutMs: ctx.timeoutMs,
+        });
+        if (compiled.code !== 0) {
+            await ctx.log(`osacompile failed (code ${compiled.code}): ${compiled.stderr.trim()} — falling back to unbranded`);
+            return undefined;
+        }
+        // Drop the GoCode icon into the bundle so the banner is branded with it.
+        // The applet's icon file is Contents/Resources/applet.icns. We convert the
+        // 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(() => { });
+        // 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 {
+            const dir = desktopDir(ctx);
+            for (const entry of await fs.readdir(dir)) {
+                if (entry.startsWith(".bundle-v")) {
+                    await fs.rm(path.join(dir, entry), { force: true }).catch(() => { });
+                }
+            }
+            await fs.writeFile(versionMarker, "", { encoding: "utf8", mode: 0o600 });
+        }
+        catch {
+            // marker is an optimization — a failed write just means we recompile next
+            // time (correct, just slightly wasteful). Never fail the banner over it.
+        }
+        return appletBin;
+    }
+    catch (err) {
+        await ctx.log(`branded app setup error: ${err instanceof Error ? err.message : String(err)} — falling back to unbranded`);
+        return undefined;
+    }
+}
+/** Best-effort: convert the bundled PNG to icns and replace the applet icon. */
+async function brandMacIcon(appPath, ctx) {
+    const png = bundledIconPath("png");
+    if (!png)
+        return;
+    try {
+        await fs.access(png);
+    }
+    catch {
+        return; // asset missing — keep the default applet icon (still name-branded)
+    }
+    const icnsTarget = path.join(appPath, "Contents", "Resources", "applet.icns");
+    const res = await ctx.run("sips", ["-s", "format", "icns", png, "--out", icnsTarget], {
+        timeoutMs: ctx.timeoutMs,
+    });
+    if (res.code !== 0) {
+        await ctx.log(`icon conversion skipped (sips code ${res.code}) — banner is name-branded only`);
+    }
+}
+/**
+ * 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
+ * `"<app>\t<projectPath>"`; when it's undefined we truncate the file to empty so
+ * a click on this banner no-ops rather than re-opening a STALE target from a
+ * previous banner. Best-effort — the caller swallows any error.
+ */
+export async function writeMacClickTarget(click, opts) {
+    const file = macClickTargetPath(opts);
+    await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    // Strip tabs/newlines from fields so the single-line TSV format can't be
+    // broken by a weird app name or path (paths with tabs are not a thing we hit,
+    // but defend anyway). Empty content when no target → click no-ops.
+    const content = click
+        ? `${oneLine(click.app)}\t${oneLine(click.projectPath)}\n`
+        : "";
+    await fs.writeFile(file, content, { encoding: "utf8", mode: 0o600 });
+}
+/** Collapse tabs/newlines to spaces so a value is safe in the single-line TSV. */
+function oneLine(s) {
+    return s.replace(/[\t\r\n]+/g, " ").trim();
+}
+async function notifyMac(banner, ctx) {
+    // Branded path: invoke the compiled GoCode.app applet so the banner is
+    // attributed to "GoCode" (+ our icon) instead of "Script Editor".
+    if (!ctx.skipBranding) {
+        const applet = await ensureMacBrandedApp(ctx);
+        if (applet) {
+            // Record the click target BEFORE posting, so a click on the banner we're
+            // about to show opens the right IDE/project (last-write-wins — the user
+            // clicks the banner they just saw). We ONLY write when THIS banner has a
+            // click target: a later display-only banner (no IDE source, e.g. a webhook
+            // ping) must NOT clear an earlier clickable banner's target, or clicking
+            // that still-visible earlier banner would no-op. Best-effort: a failed
+            // write just means the click no-ops (the banner still shows). (macOS only
+            // surfaces one process-wide applet, so this is a single shared file; the
+            // window between two clickable banners that target DIFFERENT projects is
+            // the known limit of the zero-dep applet approach — see header.)
+            if (banner.click) {
+                await writeMacClickTarget(banner.click, ctx).catch(() => { });
+            }
+            // The compiled applet reads the banner text from the environment (via
+            // AppleScript `system attribute`), so we pass it as env vars rather than
+            // recompiling per banner.
+            const res = await ctx.run(applet, [], {
+                timeoutMs: ctx.timeoutMs,
+                env: {
+                    ...(ctx.env ?? {}),
+                    GOCODE_NOTIFY_TITLE: banner.title,
+                    GOCODE_NOTIFY_MESSAGE: banner.body,
+                    GOCODE_NOTIFY_SOUND: banner.sound ? "1" : "0",
+                },
+            });
+            if (res.code === 0) {
+                await ctx.log(`branded banner shown (${banner.title})`);
+                return { ok: true, platform: "darwin" };
+            }
+            await ctx.log(`branded applet failed (code ${res.code}): ${res.stderr.trim()} — falling back to osascript`);
+        }
+    }
+    // Fallback: plain unbranded osascript (shows "Script Editor" but still works).
+    const t = escapeAppleScript(banner.title);
+    const b = escapeAppleScript(banner.body);
+    const soundClause = banner.sound ? ' sound name "Glass"' : "";
+    const script = `display notification "${b}" with title "${t}"${soundClause}`;
+    const res = await ctx.run("osascript", ["-e", script], { timeoutMs: ctx.timeoutMs });
+    if (res.code === 0) {
+        await ctx.log(`unbranded banner shown (${banner.title})`);
+        return { ok: true, platform: "darwin" };
+    }
+    await ctx.log(`osascript failed (code ${res.code}): ${res.stderr.trim()}`);
+    return { ok: false, platform: "darwin", error: res.stderr.trim() || `osascript exit ${res.code}` };
+}
+// ── Windows ──────────────────────────────────────────────────────────────────
+/**
+ * Build the inline PowerShell that (1) ensures a Start-Menu shortcut carrying
+ * our AUMID exists so Windows brands the toast "GoCode", then (2) raises a WinRT
+ * ToastGeneric toast bound to that AUMID. Pure PowerShell + WinRT — no modules.
+ */
+export function buildWindowsToastScript(banner, opts = {}) {
+    const aumid = opts.aumid ?? WINDOWS_AUMID;
+    const title = escapeXml(banner.title);
+    const body = escapeXml(banner.body);
+    const iconLine = opts.iconPath
+        ? `<image placement="appLogoOverride" hint-crop="circle" src="${escapeXml(opts.iconPath)}"/>`
+        : "";
+    const audioLine = banner.sound ? "" : '<audio silent="true"/>';
+    // The shortcut-ensure block creates a .lnk in the user's Start Menu with the
+    // System.AppUserModel.ID property = our AUMID (required for an unpackaged app
+    // to brand a toast). Idempotent: skipped when the shortcut already exists.
+    return [
+        "$ErrorActionPreference = 'Stop'",
+        `$AppId = '${escapePowerShellSingleQuoted(aumid)}'`,
+        "$AppName = 'GoCode'",
+        "$startMenu = [Environment]::GetFolderPath('Programs')",
+        "$lnk = Join-Path $startMenu 'GoCode.lnk'",
+        // Ensure a Start-Menu shortcut whose AppUserModelID = our AUMID exists. An
+        // unpackaged app MUST have such a shortcut for Windows to brand its toast
+        // (name + icon) off the AUMID. Done once; skipped when already present.
+        "if (-not (Test-Path $lnk)) {",
+        "  try {",
+        "    $ws = New-Object -ComObject WScript.Shell",
+        "    $s = $ws.CreateShortcut($lnk)",
+        "    $s.TargetPath = (Join-Path $env:SystemRoot 'System32\\\\cmd.exe')",
+        "    $s.Arguments = '/c rem GoCode Notify'",
+        "    $s.IconLocation = (Join-Path $env:SystemRoot 'System32\\\\cmd.exe') + ',0'",
+        "    $s.Save()",
+        // Stamp System.AppUserModel.ID onto the shortcut via the Windows property
+        // store (the ONLY thing that actually links the .lnk to our AUMID).
+        "    $code = @'",
+        "using System;",
+        "using System.Runtime.InteropServices;",
+        "public static class GoCodeLnk {",
+        "  [ComImport, Guid(\"00021401-0000-0000-C000-000000000046\")] public class CShellLink {}",
+        "  [ComImport, Guid(\"000214F9-0000-0000-C000-000000000046\"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]",
+        "  public interface IShellLinkW {",
+        "    void GetPath([Out] System.Text.StringBuilder f, int c, IntPtr d, int g); void GetIDList(out IntPtr p); void SetIDList(IntPtr p);",
+        "    void GetDescription(System.Text.StringBuilder n, int c); void SetDescription(string n); void GetWorkingDirectory(System.Text.StringBuilder d, int c);",
+        "    void SetWorkingDirectory(string d); void GetArguments(System.Text.StringBuilder a, int c); void SetArguments(string a);",
+        "    void GetHotkey(out short h); void SetHotkey(short h); void GetShowCmd(out int s); void SetShowCmd(int s);",
+        "    void GetIconLocation(System.Text.StringBuilder p, int c, out int i); void SetIconLocation(string p, int i);",
+        "    void SetRelativePath(string p, int r); void Resolve(IntPtr h, int f); void SetPath(string p);",
+        "  }",
+        "  [ComImport, Guid(\"45e2b4ae-b1c3-11d0-b92f-00a0c90312e1\"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]",
+        "  public interface IShellLinkDataList { void AddDataBlock(IntPtr d); void CopyDataBlock(uint s, out IntPtr d); void RemoveDataBlock(uint s); void GetFlags(out uint f); void SetFlags(uint f); }",
+        "  [StructLayout(LayoutKind.Sequential)] public struct PROPERTYKEY { public Guid fmtid; public uint pid; }",
+        "  [ComImport, Guid(\"886d8eeb-8cf2-4446-8d02-cdba1dbdcf99\"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]",
+        "  public interface IPropertyStore { void GetCount(out uint c); void GetAt(uint i, out PROPERTYKEY k); void GetValue(ref PROPERTYKEY k, out PROPVARIANT v); void SetValue(ref PROPERTYKEY k, ref PROPVARIANT v); void Commit(); }",
+        "  [StructLayout(LayoutKind.Explicit)] public struct PROPVARIANT { [FieldOffset(0)] public ushort vt; [FieldOffset(8)] public IntPtr p; }",
+        "  [DllImport(\"ole32.dll\")] public static extern int PropVariantClear(ref PROPVARIANT pv);",
+        "  [DllImport(\"shell32.dll\", CharSet=CharSet.Unicode)] public static extern IntPtr SHStrDupW(string s, out IntPtr o);",
+        "  public static void SetAumid(string lnk, string aumid) {",
+        "    var link = (IShellLinkW)new CShellLink(); var pf = (System.Runtime.InteropServices.ComTypes.IPersistFile)link; pf.Load(lnk, 0);",
+        "    var ps = (IPropertyStore)link; var key = new PROPERTYKEY { fmtid = new Guid(\"9F4C2855-9F79-4B39-A8D0-E1D42DE1D5F3\"), pid = 5 };",
+        "    var pv = new PROPVARIANT { vt = 31 }; IntPtr str; SHStrDupW(aumid, out str); pv.p = str;",
+        "    ps.SetValue(ref key, ref pv); ps.Commit(); pf.Save(lnk, true); PropVariantClear(ref pv);",
+        "  }",
+        "}",
+        "'@",
+        "    Add-Type -TypeDefinition $code -Language CSharp | Out-Null",
+        "    [GoCodeLnk]::SetAumid($lnk, $AppId)",
+        "  } catch {}",
+        "}",
+        "[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime] | Out-Null",
+        "[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType=WindowsRuntime] | Out-Null",
+        "$template = @\"",
+        "<toast>",
+        "  <visual>",
+        '    <binding template="ToastGeneric">',
+        `      <text>${title}</text>`,
+        `      <text>${body}</text>`,
+        `      ${iconLine}`,
+        "    </binding>",
+        "  </visual>",
+        `  ${audioLine}`,
+        "</toast>",
+        "\"@",
+        "$xml = New-Object Windows.Data.Xml.Dom.XmlDocument",
+        "$xml.LoadXml($template)",
+        "$toast = [Windows.UI.Notifications.ToastNotification]::new($xml)",
+        "$notifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($AppId)",
+        "$notifier.Show($toast)",
+    ].join("\n");
+}
+async function notifyWindows(banner, ctx) {
+    const iconPath = bundledIconPath("png");
+    const script = buildWindowsToastScript(banner, {
+        aumid: WINDOWS_AUMID,
+        iconPath: ctx.skipBranding ? undefined : iconPath,
+    });
+    // Run via powershell with stdin so we never hit cmd-line length / quoting limits.
+    const res = await ctx.run("powershell", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", "-"], { input: script, timeoutMs: ctx.timeoutMs });
+    if (res.code === 0) {
+        await ctx.log(`toast shown (${banner.title})`);
+        return { ok: true, platform: "win32" };
+    }
+    await ctx.log(`powershell toast failed (code ${res.code}): ${res.stderr.trim()}`);
+    return { ok: false, platform: "win32", error: res.stderr.trim() || `powershell exit ${res.code}` };
+}
+// ── Linux ────────────────────────────────────────────────────────────────────
+async function notifyLinux(banner, ctx) {
+    const icon = bundledIconPath("png");
+    const args = ["-a", APP_NAME];
+    if (icon && !ctx.skipBranding)
+        args.push("-i", icon);
+    // Best-effort sound control: there is no portable notify-send sound flag, but
+    // the freedesktop `suppress-sound` hint is honoured by GNOME/KDE daemons, so
+    // map `sound:false` → suppress. (Daemons that ignore the hint just play their
+    // default — no portable way to force-silence those, hence "best effort".)
+    if (!banner.sound)
+        args.push("-h", "int:suppress-sound:1");
+    // notify-send positional args: <summary> [body]
+    args.push(banner.title);
+    if (banner.body)
+        args.push(banner.body);
+    const res = await ctx.run("notify-send", args, { timeoutMs: ctx.timeoutMs });
+    if (res.code === 0) {
+        await ctx.log(`notify-send banner shown (${banner.title})`);
+        return { ok: true, platform: "linux" };
+    }
+    await ctx.log(`notify-send failed (code ${res.code}): ${res.stderr.trim()}`);
+    return { ok: false, platform: "linux", error: res.stderr.trim() || `notify-send exit ${res.code}` };
+}

package/dist/src/notify_copy.js

@@ -0,0 +1,189 @@
+// `notify_copy` — the ONE place the desktop banner's wording is built so it
+// reads WORD-FOR-WORD identical to the phone push (GOCODE_NOTIFY_DESKTOP PRD
+// §3 "same title/body as the phone"). This is a faithful port of the server's
+// decoration (`dispatcher._decorated_title` / `_decorated_body` +
+// `notify_routes._DEFAULT_TITLES` / `_DEFAULT_BODIES`) AND the Flutter client's
+// `decorateNotificationTitle` / `sourceLabelFor` (`push_notification_service.dart`
+// / `firebase_push_notification_service.dart`). All three MUST agree — there is a
+// cross-check test (`notify_copy.test.ts`) that pins these tables against the
+// server/Flutter strings so a future edit on one side can't silently drift.
+//
+// Why mirror server-side copy in the CLI at all? The desktop banner fires
+// LOCALLY (it never round-trips the server — that would add latency + a failure
+// mode to a best-effort banner), so the CLI must reproduce the exact string the
+// server would have rendered for the phone. Keeping it in its own tiny module
+// (rather than inline in `on_stop.ts`) makes the "single source of truth, pinned
+// by a test" contract explicit.
+//
+// Zero runtime deps — pure string logic, no imports.
+/**
+ * Max display length for a project / chat name folded into the title or body.
+ * Mirrors the server's `_NOTIFICATION_NAME_MAX_LEN` and the Flutter client's
+ * `kNotificationNameMaxLen` so a long name truncates to the SAME string the
+ * phone shows.
+ */
+export const NOTIFICATION_NAME_MAX_LEN = 40;
+/**
+ * Per-kind status emoji prefixed onto the decorated title. Mirrors the server's
+ * `_STATUS_EMOJI` and the Flutter client's `_statusEmojiFor`. Unknown kinds get
+ * no emoji (fall through), exactly like the server.
+ */
+const STATUS_EMOJI = {
+    finished: "✅",
+    loop_completed: "✅",
+    error: "❌",
+    awaiting_input: "❓",
+    ralph_waiting: "❓",
+    loop_halted: "⚠️",
+};
+/**
+ * Per-kind DEFAULT title used when the caller supplies no explicit title — the
+ * funnel/stop-hook path always omits a title, so this is what the phone shows.
+ * Mirrors the server's `notify_routes._DEFAULT_TITLES` (chat kinds) +
+ * `dispatcher.LOOP_KIND_COPY` (loop kinds) EXACTLY. Keep these strings in sync
+ * with the server — the cross-check test pins them.
+ */
+export const DEFAULT_TITLES = {
+    finished: "Agent finished",
+    error: "Agent hit an error",
+    awaiting_input: "Agent needs you",
+    loop_completed: "Autopilot finished",
+    loop_halted: "Autopilot halted — needs you",
+};
+/**
+ * Per-kind DEFAULT body used when the caller supplies no explicit body. Mirrors
+ * the server's `notify_routes._DEFAULT_BODIES` + `dispatcher.LOOP_KIND_COPY`.
+ */
+export const DEFAULT_BODIES = {
+    finished: "Your coding run finished — tap to review.",
+    error: "Your coding run hit an error — tap to see what happened.",
+    awaiting_input: "Your coding run is waiting on you — tap to respond.",
+    loop_completed: "Your Autopilot loop finished — tap to review.",
+    loop_halted: "Your Autopilot loop stopped and needs your input — tap to resolve.",
+};
+/** Loop kinds whose decorated title carries the "Autopilot" prefix (no project). */
+const AUTOPILOT_KINDS = new Set(["loop_completed", "loop_halted", "ralph_waiting"]);
+/**
+ * Human-readable source label for the title prefix. `"cursor"` → `"Cursor"`,
+ * `"claude_code"`/`"claude"` → `"Claude"`. Mirrors the Flutter client's
+ * `sourceLabelFor` and the server's `_source_label` EXACTLY: a known token maps
+ * to its brand; `"manual"`/`"app"`/`"cli"` return null (no prefix); any other
+ * token is title-cased defensively. Returns null when there is no label.
+ */
+export function sourceLabelFor(source) {
+    if (source == null)
+        return undefined;
+    const s = source.trim().toLowerCase();
+    if (s === "")
+        return undefined;
+    switch (s) {
+        case "gocode":
+            return "GoCode";
+        case "cursor":
+            return "Cursor";
+        case "claude_code":
+        case "claude":
+            return "Claude";
+        case "opencode":
+            return "OpenCode";
+        case "ralph":
+            return "Ralph";
+        case "homer":
+            return "Homer";
+        // In-app origins carry no brand prefix (mirror Flutter/`_source_label`).
+        case "manual":
+        case "app":
+        case "cli":
+            return undefined;
+        default: {
+            // Title-case an unknown token so a new server source still renders
+            // something sensible (mirrors Flutter's defensive default + the server).
+            const t = source.trim();
+            return t.charAt(0).toUpperCase() + t.slice(1);
+        }
+    }
+}
+/**
+ * Trim + cap a project / chat name at {@link NOTIFICATION_NAME_MAX_LEN},
+ * appending an ellipsis when truncated. Returns undefined when the name is
+ * empty/whitespace so a blank field never folds an empty segment into the
+ * title/body. Mirrors the server's `_truncate_notification_name` and the
+ * client's `truncateNotificationName`.
+ */
+export function truncateNotificationName(name) {
+    if (name == null)
+        return undefined;
+    const n = name.trim();
+    if (n === "")
+        return undefined;
+    if (n.length <= NOTIFICATION_NAME_MAX_LEN)
+        return n;
+    // Reserve one char for the ellipsis so the result length equals the cap.
+    return n.slice(0, NOTIFICATION_NAME_MAX_LEN - 1) + "…";
+}
+/**
+ * Build the OS-rendered banner title — WORD-FOR-WORD identical to the phone push.
+ * Format: `<emoji> <source label> · <project> · Autopilot — <title>`, omitting
+ * any empty segment. A faithful port of the server's `_decorated_title` and the
+ * Flutter client's `decorateNotificationTitle` (the project segment is suppressed
+ * for autopilot/loop kinds, exactly like both). Idempotent on the emoji.
+ */
+export function decorateTitle(input) {
+    const kind = input.kind;
+    const autopilot = AUTOPILOT_KINDS.has(kind);
+    const rawTitle = input.title != null && input.title.trim() !== ""
+        ? input.title
+        : DEFAULT_TITLES[kind] ?? "";
+    const emoji = STATUS_EMOJI[kind];
+    const label = sourceLabelFor(input.source);
+    // Project is folded into the title for IDE/funnel pushes, but NOT for
+    // autopilot pushes (whose title already reads "<tool> · Autopilot — …").
+    const projectLabel = autopilot ? undefined : truncateNotificationName(input.project);
+    const prefixParts = [];
+    if (label)
+        prefixParts.push(label);
+    if (projectLabel)
+        prefixParts.push(projectLabel);
+    if (autopilot)
+        prefixParts.push("Autopilot");
+    const prefix = prefixParts.join(" · ");
+    // Defend against a caller that already prepended the emoji to the raw title.
+    let base = rawTitle.replace(/^\s+/, "");
+    if (emoji && base.startsWith(emoji)) {
+        base = base.slice(emoji.length).replace(/^\s+/, "");
+    }
+    const emojiS = emoji ?? "";
+    if (prefix) {
+        const left = `${emojiS} ${prefix}`.trim();
+        if (base === "")
+            return left;
+        return `${left} — ${base}`;
+    }
+    // No source/autopilot prefix.
+    if (base === "")
+        return emojiS;
+    return emojiS ? `${emojiS} ${base}`.trim() : base;
+}
+/**
+ * Build the OS-rendered banner body — matching the phone push. Folds the project
+ * (+ optional chat title) into the body: `<project> · <body>` or
+ * `<project> › <chat> · <body>`. A faithful port of the server's `_decorated_body`
+ * and the client's `decorateNotificationBody`. When no body is supplied the
+ * per-kind {@link DEFAULT_BODIES} is used so the banner is never body-less (the
+ * phone is never title-only either).
+ */
+export function decorateBody(input) {
+    const raw = input.body != null && input.body.trim() !== ""
+        ? input.body
+        : DEFAULT_BODIES[input.kind] ?? "";
+    const base = raw.trim() !== "" ? raw.trim() : undefined;
+    const proj = truncateNotificationName(input.project);
+    const conv = truncateNotificationName(input.chat);
+    const contextParts = [proj, conv].filter((p) => p != null);
+    if (contextParts.length === 0)
+        return base ?? "";
+    const context = contextParts.join(" › ");
+    if (base == null)
+        return context;
+    return `${context} · ${base}`;
+}

package/dist/src/on_stop.js

@@ -33,6 +33,8 @@ import { deriveRepoIdentity } from "./repo_key.js";
 import { pushOnStop, } from "./push.js";
 import { appendLog, send } from "./send.js";
 import { checkDedupLock } from "./dedup_lock.js";
+import { notifyDesktop, } from "./desktop_notify.js";
+import { decorateTitle, decorateBody } from "./notify_copy.js";
 /**
  * Parse the Cursor `stop` hook stdin JSON and extract the `status` field.
  * Best-effort: returns `undefined` on absent/empty/unparseable input or when the
@@ -118,6 +120,74 @@ export function cursorStopStatusToKind(status) {
 export function shouldSuppressAbortedStop(source, status) {
     return source === "cursor" && status === "aborted";
 }
+/**
+ * Human-readable label for a notification kind, used in the desktop banner body
+ * (PRD §3). Mirrors the phone notification's tone so the computer banner reads
+ * the same. Falls back to the raw kind for any future/unknown value.
+ */
+export function kindLabel(kind) {
+    switch (kind) {
+        case "finished":
+            return "Finished";
+        case "error":
+            return "Error";
+        case "awaiting_input":
+            return "Needs your input";
+        case "loop_completed":
+            return "Autopilot finished";
+        case "loop_halted":
+            return "Autopilot halted — needs you";
+        case "ralph_waiting":
+            return "Autopilot waiting";
+        default:
+            return String(kind);
+    }
+}
+/**
+ * Map a notification `source` (the IDE that raised the turn) to the macOS app
+ * name `open -a <app>` should launch, and the Windows process name. Returns
+ * undefined for non-IDE / unknown sources so the banner is display-only rather
+ * than opening the wrong thing. We intentionally cover ONLY the editors that run
+ * a stop hook (Cursor / Claude Code / OpenCode) — Autopilot/Ralph/Homer loops
+ * have no local IDE window to focus, and `manual`/webhook sources aren't IDEs.
+ */
+export function ideAppNameFor(source) {
+    if (!source)
+        return undefined;
+    switch (source.trim().toLowerCase()) {
+        case "cursor":
+            return "Cursor";
+        case "claude":
+        case "claude_code":
+            // Claude Code is a CLI inside a terminal/VS Code; "Visual Studio Code" is
+            // the closest reliable window to focus when it runs inside VS Code. When
+            // it runs in a bare terminal there is no stable app to open, so callers
+            // fall back gracefully (the click just no-ops rather than mis-opening).
+            return "Visual Studio Code";
+        case "opencode":
+            return "Visual Studio Code";
+        default:
+            return undefined;
+    }
+}
+/**
+ * Build the best-effort click target for the desktop banner (PRD §3.6): clicking
+ * the banner opens the IDE window for the project at `cwd`. Returns undefined
+ * when we can't name an IDE for `source` (then the banner is display-only — a
+ * graceful no-click, never a dead/mis-routed click). The `cwd` is the project
+ * directory the agent ran in, so `open -a <ide> <cwd>` focuses (or opens) that
+ * IDE on the right project window. `ideChatId` is carried for future use (deep
+ * link to the exact chat) but not required to open the window.
+ */
+export function clickTarget(source, cwd, _ideChatId) {
+    const app = ideAppNameFor(source);
+    if (!app)
+        return undefined;
+    const projectPath = cwd && cwd.trim() !== "" ? cwd : undefined;
+    if (!projectPath)
+        return undefined;
+    return { app, projectPath };
+}
 /** Slice the merged settings down to what the push flow consumes. */
 function toPushSettings(settings) {
     return {
@@ -493,6 +563,46 @@ export async function onStop(opts = {}) {
             timeoutMs: opts.timeoutMs,
             timestamp: opts.timestamp,
         }));
+    const desktopImpl = opts.notifyDesktopImpl ?? notifyDesktop;
+    /**
+     * Fire a branded local desktop banner for this turn (PRD §3) when
+     * `settings.desktop.enabled` is true. Best-effort + total: never throws, and
+     * the result is purely informational (the phone push is the source of truth).
+     * Gated on the SAME server-synced settings as the phone push so a toggle on
+     * the app or terminal flips the computer banner too. Returns undefined when
+     * desktop is disabled (so the result field is omitted).
+     */
+    const fireDesktop = async (settings, banner, source, ideChatId) => {
+        if (settings.desktop?.enabled === false)
+            return undefined;
+        if (opts.dryRun) {
+            await logLine(`dry-run: would show desktop banner "${banner.title ?? ""}"`);
+            return undefined;
+        }
+        try {
+            const res = await desktopImpl({
+                ...banner,
+                sound: settings.desktop?.sound !== false,
+                // Best-effort click target (PRD §3.6): clicking the banner opens the
+                // IDE window for THIS project (the agent's cwd), the same IDE that
+                // raised the turn. Omitted when we can't name the IDE or the path —
+                // then the banner is display-only (graceful, never a dead click).
+                click: clickTarget(source, cwd, ideChatId),
+            }, {
+                home: opts.home,
+                timeoutMs: opts.timeoutMs,
+                timestamp: opts.timestamp,
+            });
+            await logLine(`desktop banner → ${res.ok ? "shown" : "failed"} (${res.platform})`);
+            return res;
+        }
+        catch (err) {
+            // desktop banner must never block the turn — but leave a breadcrumb so a
+            // throwing (injected/future) impl is diagnosable from the notify log.
+            await logLine(`desktop banner threw — ignored: ${err instanceof Error ? err.message : String(err)}`);
+            return undefined;
+        }
+    };
     try {
         // ── Step 0: Autopilot-owns-turn gate (T-N7 / PRD §3.2). ──
         // When an Autopilot loop has marked that it owns this turn, it sends its OWN
@@ -564,7 +674,26 @@ export async function onStop(opts = {}) {
                 home: opts.home,
             });
             await logLine(`auto-push path → ${push.outcome} (source: ${source}, settings: ${resolved.source})`);
-            return { mode: "push", settingsSource: resolved.source, push, repo, detail: push.detail };
+            // Branded desktop banner mirroring the push notification (PRD §3). Only
+            // fire when the push flow actually notified the phone (i.e. it pushed,
+            // hit a conflict, or was rejected) — not on no-op outcomes (disabled /
+            // not-a-repo / clean-tree / protected-skip) where the phone got nothing.
+            let desktop;
+            if (push.notified === true) {
+                const project = projectLabel(repo, cwd);
+                const isError = push.outcome === "conflict-aborted" || push.outcome === "push-rejected";
+                const pushKind = isError ? "error" : "finished";
+                // Decorate WORD-FOR-WORD like the phone push (PRD §3): the auto-push
+                // path leaves `title` to the server default per kind, and folds the
+                // project into title + body exactly as `dispatcher._decorated_*` does.
+                const rawBody = push.detail || (isError ? "Auto-push needs you" : `Pushed to ${push.branch ?? "branch"}`);
+                desktop = await fireDesktop(settings, {
+                    title: decorateTitle({ kind: pushKind, source, project }),
+                    body: decorateBody({ kind: pushKind, body: rawBody, project }),
+                    kind: pushKind,
+                }, source);
+            }
+            return { mode: "push", settingsSource: resolved.source, push, desktop, repo, detail: push.detail };
         }
         // ── Step 3b: auto-push off → the plain notification (legacy flow). ──
         // Derive the notification kind from the Cursor stop hook's stdin JSON (T-CUR1
@@ -622,9 +751,27 @@ export async function onStop(opts = {}) {
         const chatTitle = await chatTitleFromHookStdin(opts.hookStdin);
         if (chatTitle)
             payload.chat = chatTitle;
-        const sent = await sendImpl(payload);
+        // Fire the phone push and the branded desktop banner in parallel (PRD §3):
+        // the computer gets told the same instant the phone does, and a slow banner
+        // never delays the phone send. The banner reuses the SAME project label,
+        // kind, and (when present) chat title that the phone notification carries.
+        // Decorate the banner WORD-FOR-WORD like the phone push (PRD §3): same
+        // emoji + source label + project folded into the title, and the per-kind
+        // default body with project (+ chat title) folded in — exactly what the
+        // server's `_decorated_title`/`_decorated_body` produce for this push. The
+        // CLI omits an explicit title (like the phone send) so the per-kind default
+        // ("Agent finished" / …) flows through identically on both surfaces.
+        const desktopBanner = {
+            title: decorateTitle({ kind: sendKind, source, project }),
+            body: decorateBody({ kind: sendKind, project, chat: chatTitle }),
+            kind: sendKind,
+        };
+        const [sent, desktop] = await Promise.all([
+            sendImpl(payload),
+            fireDesktop(settings, desktopBanner, source, ideChatId),
+        ]);
         await logLine(`send path → ${sendKind} ${sent.ok ? "delivered" : "failed"} (source: ${source}, settings: ${resolved.source})`);
-        return { mode: "send", settingsSource: resolved.source, send: sent, repo };
+        return { mode: "send", settingsSource: resolved.source, send: sent, desktop, repo };
     }
     catch (err) {
         // Defence in depth: the dispatcher must never throw. Degrade to a logged

package/dist/src/settings.js

@@ -47,6 +47,12 @@ export const DEFAULT_NOTIFY_SETTINGS = {
         command: null,
         max_diff_bytes: 61440,
     },
+    // Branded desktop banners ON by default (PRD §3): installing the package opts
+    // you into computer notifications; flip `desktop.enabled false` to silence.
+    desktop: {
+        enabled: true,
+        sound: true,
+    },
 };
 /**
  * Every dotted setting key the CLI accepts in `config set <key> <value>`, with
@@ -74,6 +80,9 @@ export const KEY_SPECS = {
     "commit_message.mode": { kind: "enum", enumValues: ["auto", "ai", "deterministic"] },
     "commit_message.command": { kind: "string_or_null" },
     "commit_message.max_diff_bytes": { kind: "int_pos" },
+    // Branded desktop banners (GOCODE_NOTIFY_DESKTOP PRD §3) — ON by default.
+    "desktop.enabled": { kind: "boolean" },
+    "desktop.sound": { kind: "boolean" },
 };
 /** Sorted list of every valid `config set` key — for help text + error messages. */
 export function validKeys() {

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.3.4";
+export const VERSION = "0.4.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@trygocode/notify",
-  "version": "0.3.4",
-  "description": "Free phone notifications for any coding agent (Cursor, Claude Code, OpenCode, Ralph/Homer) via the GoCode app.",
+  "version": "0.4.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",
   "bin": {
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist/src",
+    "assets",
     "snippets",
     "README.md"
   ],
@@ -26,6 +27,8 @@
     "notifications",
     "push",
     "fcm",
+    "desktop-notifications",
+    "toast",
     "mcp",
     "cli",
     "claude-code",