@trygocode/notify 0.1.2 → 0.1.3

package/README.md

@@ -1,76 +1,21 @@
-<p align="center">
-  <img src="assets/icon-512.png" alt="GoCode Notify" width="104" height="104" />
-</p>
+# @trygocode/notify
 
-<h1 align="center">@trygocode/notify</h1>
+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.
 
-<p align="center">
-  <strong>Get a push notification on your phone the moment your AI coding agent finishes.</strong><br/>
-  Cursor · Claude Code · OpenCode · Ralph Wiggum / Autopilot script loops — installed with <em>one</em> command.
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/@trygocode/notify"><img alt="npm" src="https://img.shields.io/npm/v/@trygocode/notify?color=5EE6A8&label=npm"></a>
-  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
-  <img alt="price" src="https://img.shields.io/badge/price-free-5EE6A8">
-  <img alt="node" src="https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white">
-  <img alt="works with" src="https://img.shields.io/badge/works%20with-Cursor%20%C2%B7%20Claude%20Code%20%C2%B7%20OpenCode-111">
-</p>
-
-```bash
-npx @trygocode/notify@latest setup
-```
-
-<p align="center">
-  <img src="assets/banner.png" alt="GoCode Notify" width="640" />
-</p>
-
-> **Free.** `@trygocode/notify` and the **[GoCode](https://oh.jeltechsolutions.com)** phone app
-> that receives the pushes are both free to use.
->
-> **You need the GoCode app.** Notifications are delivered to your phone through the free GoCode
-> app — it's the pairing target and the thing your phone buzzes with. Install it, pair once
-> (a 6-digit code), done. Without it there's nowhere for the pushes to land.
-
----
-
-## Why?
-
-You kick off a long agent run, then walk away to make coffee, take a call, or
-context-switch to something else. Now you're stuck in the loop of *checking back
-every 30 seconds* to see if it's done — or worse, it finished 20 minutes ago and
-you didn't notice.
-
-**`@trygocode/notify` pings your phone the instant your agent finishes a turn, goes
-idle waiting for you, errors out, or an overnight loop completes/halts.** Walk
-away. Your phone tells you when it needs you.
-
-- 🆓 **Free.** The package and the GoCode phone app are free. No card, no trial.
-- ⚡ **One command.** `npx @trygocode/notify@latest setup` — no server to host, no config files to hand-edit.
-- 🔒 **Push-only & private.** The paired key can *only* send notifications to your phone. It can't read your chats, code, or settings. Revoke it any time.
-- 🧩 **Auto-detects your tools.** Wires up Cursor, Claude Code, and OpenCode in one go — never clobbering your existing hooks/MCP config.
-- 🪶 **Never blocks your agent.** Every send is fire-and-forget with a hard timeout + an offline queue. A slow push can't slow your work.
-
-## Works with
-
-| Tool | How it hooks in |
-|---|---|
-| **Cursor** | `stop` hook |
-| **Claude Code** | `Stop` + `Notification` + `SubagentStop` hooks |
-| **OpenCode** | runtime hook |
-| **Ralph Wiggum / Autopilot script loops** | opt-in completion/halt snippet |
-
-> **Requires the free [GoCode](https://oh.jeltechsolutions.com) phone app.** It's the one-time
-> pairing target and where every push lands. Install GoCode, pair once, done — both the app and
-> this package are free.
+You get an automatic push 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.
 
 ## Contents
 
 - [Install — two equally-supported paths](#install--two-equally-supported-paths)
 - [Pairing — step by step](#pairing--step-by-step)
 - [The three triggers](#the-three-triggers)
-- [Loop opt-in snippet (trigger C)](#loop-opt-in-snippet-trigger-c)
-- [GoCode platform settings (auto-push, pull-before-push & more)](#gocode-platform-settings)
+- [Auto-push to git (opt-in)](#auto-push-to-git-opt-in)
+- [Settings sync — the `config` command](#settings-sync--the-config-command)
+- [Ralph/Homer opt-in snippet (trigger C)](#ralphhomer-opt-in-snippet-trigger-c)
 - [Troubleshooting](#troubleshooting)
 - [Develop](#develop)
 - [Layout](#layout)
@@ -93,9 +38,10 @@ This runs the interactive installer: it prompts for the 6-digit pairing code
 Claude Code / Cursor / OpenCode. Re-run any time — it's idempotent; pass
 `--force` to re-pair.
 
-> First time? You'll need the free **[GoCode](https://oh.jeltechsolutions.com)**
-> app on your phone to receive the pushes and to generate the 6-digit pairing
-> code (Settings → **"Connect a coding agent"**).
+> Until the package is published to npm, point `npx` at the local tarball
+> (`npm pack` in this directory, then `npx ./gocode-notify-*.tgz setup`) or a
+> path install. The npm publish is a user-owned step — see
+> [`docs/GOCODE_NOTIFY_MANUAL_STEPS.md`](../../docs/GOCODE_NOTIFY_MANUAL_STEPS.md).
 
 ### Path 2 — paste a prompt into your AI agent and let it install
 
@@ -163,26 +109,168 @@ or staging GoCode server.
 
 | Trigger | Mechanism | Fires when |
 |---|---|---|
-| **(A) Runtime hook** | Cursor `stop` / Claude Code `Stop`+`Notification`+`SubagentStop` | Agent finishes a turn, goes idle, or errors — **automatic, the killer feature** |
+| **(A) Runtime hook** | Cursor `stop` / Claude Code `Stop`+`Notification`+`SubagentStop` / OpenCode `session.idle` plugin | Agent finishes a turn, goes idle, or errors — **automatic, the killer feature** |
 | **(B) MCP tool** | `gocode_notify` tool the agent calls | You *explicitly* ask "ping me when X is done" mid-task |
-| **(C) Loop shell hook** | one line in your loop's completion/halt path | A Ralph Wiggum / Autopilot script loop reaches `completed` / `halted` |
+| **(C) Loop shell hook** | one line in your loop's completion/halt path | A Ralph/Homer loop reaches `completed` / `halted` |
 
 The installed rule/skill tells the agent **not** to call the MCP tool for
 done/idle/error pings — those are owned by the deterministic hook (A), so you
 never get double-pinged.
 
-## Loop opt-in snippet (trigger C)
+> **OpenCode's hook (A)** is a small `session.idle` plugin written to
+> `~/.config/opencode/plugin/gocode-notify.js`; on each `session.idle` event it
+> fire-and-forgets `gocode-notify on-stop --source opencode` (the same
+> dispatcher as Cursor/Claude), so OpenCode is a fully-supported runtime with
+> identical behaviour.
+
+> **Under the hood (since auto-push landed):** the runtime hook (A) no longer
+> shells straight to `send`. It now calls a single end-of-turn **dispatcher**,
+> `gocode-notify on-stop --source <runtime> || true`, which decides per repo:
+> if auto-push is enabled for this repo it runs the push flow (and sends ONE
+> notification carrying the commit summary); otherwise it sends the ordinary
+> `finished` ping exactly as before. One hook entry, one notification per turn.
+> Existing installs upgrade their hook automatically on the next
+> `setup`/`setup --force`. `send` and `test` remain callable on their own for
+> scripts and power users.
+
+## Auto-push to git (opt-in)
+
+GoCode Notify can **auto-commit and push your work after every agent turn** —
+with an **AI-written commit message** describing what just changed — so an
+overnight Cursor/Claude/Ralph session lands as a tidy series of pushed commits
+and your phone tells you each time, commit summary included.
+
+It is **OFF by default** and deliberately conservative (see the safety posture
+below). The full design lives in
+[`docs/GOCODE_NOTIFY_AUTO_PUSH_AND_SYNC.md`](../../docs/GOCODE_NOTIFY_AUTO_PUSH_AND_SYNC.md).
+
+### Enable it
+
+From the **GoCode app** (Settings → **GoCode Notify** → *Auto-push after every
+prompt*; a first-enable dialog explains the behaviour), or from the terminal:
+
+```bash
+# Turn auto-push on for ALL repos (global default):
+gocode-notify config set auto_push.enabled true
+
+# Or scope it to just the current repo:
+gocode-notify config set auto_push.enabled true --repo
+```
 
-For power users running an autonomous loop **they control** — a *Ralph Wiggum*-style
-"keep prompting until done" loop, an Autopilot script, a `while :; do … done`
-one-liner, or any custom driver — drop these two lines into the loop's
-completion/halt path:
+Either editor writes to the server (the single source of truth); the change is
+picked up by every linked machine on its next turn (within the 60s settings
+cache, or immediately after `gocode-notify config pull`).
+
+### What happens on each turn (when enabled)
+
+The `on-stop` dispatcher runs this best-effort push flow (it **always exits 0**
+so a git hiccup can never block or fail your agent's turn):
+
+1. Resolve the merged Notify settings for this repo (cached ~60s).
+2. If `auto_push.enabled` is not true for the repo → no-op (plain ping).
+3. Verify it's a git repo; resolve the target branch (per-repo override →
+   global default → current checked-out branch).
+4. **Branch guard:** never push to `main`/`master` unless you have separately
+   set `auto_push.allow_protected true`. Protected + not allowed → skip, no push.
+5. `git add -A`; if the tree is clean → exit 0 (no spurious notification).
+6. Compose the commit message (AI, with deterministic fallback — see below).
+7. `git commit` then `git push <remote> <branch>` — **fast-forward only, never
+   `--force`.** A non-FF rejection sends an `error` notification ("auto-push
+   rejected — pull + retry") and exits 0.
+8. Send ONE `finished` push whose body carries the commit summary, branch, and
+   short SHA.
+
+### The AI commit message (free) + deterministic fallback
+
+The commit subject/body is summarised **using credentials you already have on
+the machine** — so it costs GoCode nothing. Resolution chain (first that works
+wins, hard **8s** cap):
+
+1. `commit_message.mode = "deterministic"` → skip AI, use the template below.
+2. Otherwise an explicit `commit_message.command` (e.g. `"claude -p"`,
+   `"cursor-agent --print"`, `"ollama run llama3.2"`) — the staged diff is
+   piped in on stdin with a fixed prompt; output is sanitised (code fences /
+   "Here is…" preambles stripped, subject clamped to ≤72 chars).
+3. Auto-detect from `--source`: `claude` on PATH for Claude Code, `cursor-agent`
+   for Cursor, else `ollama` if present.
+4. **Deterministic fallback** (always available — used if the above fail or time
+   out): `<type>: <N> file(s) changed on <branch>` + a `git diff --stat` block,
+   where `<type>` is inferred from the changed paths (`docs:`/`test:`/`chore:`/
+   `feat:`). The push **never** fails because the AI summary was unavailable.
+
+### Try it without writing anything
+
+```bash
+# Print exactly what the end-of-turn dispatcher WOULD do (no git writes, no push):
+gocode-notify on-stop --dry-run
+```
+
+### Safety posture (conservative defaults)
+
+- **OFF by default**, opt-in, with a first-time confirmation in the app.
+- **Branch guard ON:** `main`/`master` are never auto-pushed unless
+  `auto_push.allow_protected` is explicitly true.
+- **No force-push, ever** — plain fast-forward `git push`; non-FF → error
+  notification, no rewrite.
+- **Never blocks the agent** — every step is best-effort and exits 0, the same
+  contract as `send`.
+
+## Settings sync — the `config` command
+
+Notify behaviour used to be hard-wired; now it's a small set of **per-user
+settings stored on the server** and editable from either the phone app or the
+terminal. Whatever you change in one place propagates to the other (and to your
+other linked machines).
+
+```bash
+gocode-notify config get [--repo]                 # print the merged settings (JSON/pretty)
+gocode-notify config set <key> <value> [--repo]   # validate, write to server, refresh cache
+gocode-notify config pull                          # force-refresh the local cache from server
+```
+
+- `--repo` scopes a read or write to the **current repo's** per-project
+  override (keyed by a stable `repo_key` derived from the `origin` remote)
+  instead of your global defaults. Per-repo overrides deep-merge over the global
+  blob.
+- Writes go to the server **and** update the local cache so the next stop-hook
+  is immediate. Unknown keys are rejected with the list of valid keys.
+
+Valid keys (mirror of the canonical schema):
+
+| Key | Type | Meaning |
+|---|---|---|
+| `kinds.finished` / `kinds.error` / `kinds.awaiting_input` / `kinds.loop_completed` / `kinds.loop_halted` | bool | Per-kind notification toggles |
+| `min_duration_seconds` | int ≥ 0 | Only notify if the turn ran ≥ N seconds (0 = always) |
+| `quiet_hours.enabled` / `quiet_hours.start` / `quiet_hours.end` / `quiet_hours.tz` | bool / `HH:MM` / `HH:MM` / IANA tz | Do-not-disturb window |
+| `auto_push.enabled` | bool | Master auto-push switch (OFF by default) |
+| `auto_push.default_branch` | string \| null | Global default push branch (null = current branch) |
+| `auto_push.branch` | string \| null | **`--repo` only** — per-repo push branch override |
+| `auto_push.allow_protected` | bool | Permit auto-push to `main`/`master` (default false) |
+| `auto_push.remote` | string | Git remote to push to (default `origin`) |
+| `auto_push.skip_git_hooks` | bool | Pass `--no-verify` to the auto-commit (default false) |
+| `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) |
+
+```bash
+# Examples
+gocode-notify config set quiet_hours "23:00-07:00"     # shorthand: enable + set window
+gocode-notify config set min_duration_seconds 30
+gocode-notify config set kinds.error false
+gocode-notify config set auto_push.branch dev --repo   # push this repo to "dev"
+```
+
+## Ralph/Homer opt-in snippet (trigger C)
+
+For power users running a loop **they control** (this repo's `ralph`/`homer`
+skills, a `while :; do … done` one-liner, or any custom driver), drop these two
+lines into the loop's completion/halt path:
 
 ```bash
 # At loop completion:
-npx -y @trygocode/notify send --kind loop_completed --source ralph --project "$(basename "$PWD")" || true
+gocode-notify send --kind loop_completed --source ralph --project "$(basename "$PWD")" || true
 # At loop halt (paused_max_failures / awaiting_human):
-npx -y @trygocode/notify send --kind loop_halted --source ralph --project "$(basename "$PWD")" \
+gocode-notify send --kind loop_halted --source ralph --project "$(basename "$PWD")" \
   --title "Ralph halted — needs you" || true
 ```
 
@@ -193,24 +281,6 @@ The ready-to-copy version with comments lives at
 loop scripts. Both lines are fire-and-forget (`|| true` + the CLI's 5s
 self-timeout), so a failed or slow push can never block or fail your loop.
 
-## GoCode platform settings
-
-This package is the *notifier*. The richer automation lives in the free **GoCode**
-phone app (Settings → per-project + global), which uses these notifications as its
-signalling layer. Once paired, the app gives you:
-
-| Setting | What it does |
-|---|---|
-| **Notification preferences** | Choose which events ping your phone — done / idle / error, loop completed, loop halted, agent questions, merge-ready — globally or per project. |
-| **Auto-push to git** | Opt-in: after a turn, the agent commits + pushes to a chosen branch so your work is never stranded on one machine and you can pick up anywhere. Off by default. |
-| **Pull-before-push (safe)** | When auto-push is on, a `git pull --rebase --autostash` runs first so remote changes merge cleanly. On a real conflict it aborts safely (nothing lost) and pings your phone. |
-| **AI-Solve conflicts** | If a push hits a conflict, the notification deep-links into the chat with two actions: **Acknowledge** or **AI-Solve** — your agent diagnoses local vs remote and resolves it with no code loss, asking you only when it's unsure. |
-| **Review & merge / Create PR** | When an Autopilot loop finishes on its own branch, you get a merge-ready ping; choose **Merge & push** (solo repos) or **Create PR** (teams), with a remembered default branch. |
-| **Default LLM & loop model** | Per-project defaults for the agent model and the Autopilot loop model. |
-
-> These toggles are configured **in the GoCode app**, not in this npm package — the
-> package just delivers the pings that drive them. All of it is free.
-
 ## Troubleshooting
 
 **Start here:** `gocode-notify status` prints a one-screen report — whether
@@ -225,9 +295,9 @@ been written. Most issues below are diagnosable from that output.
 | `status` shows **Server: not reachable** | Network/DNS/firewall, or a wrong server URL. Confirm you can reach `https://oh.jeltechsolutions.com`; check the `--server` flag / `GOCODE_SERVER` env / the `server` field in `~/.gocode/credentials`. |
 | **No push arrives** even though `test` exits 0 | The send is fire-and-forget and exits 0 even on failure — check `~/.gocode/notify.log` for the real error. Also confirm push permissions are granted in the GoCode app and the device token is registered (re-open the app once after signing in). |
 | **Double pings** (two notifications per event) | The agent is calling the `gocode_notify` MCP tool *and* the runtime hook is firing. Re-run `setup` so the anti-double-ping rule/skill is installed; it tells the agent not to notify for automatic done/idle/error events. |
-| **Hook doesn't fire** in Cursor / Claude Code | Re-run `setup` and check `status` shows "config written" for that runtime. Restart the agent app so it reloads `~/.cursor/hooks.json` / `~/.claude/settings.json`. The hooks are merged, never clobbered — your existing hooks are preserved. |
+| **Hook doesn't fire** in Cursor / Claude Code / OpenCode | Re-run `setup` and check `status` shows "config written" for that runtime. Restart the agent app so it reloads `~/.cursor/hooks.json` / `~/.claude/settings.json` / `~/.config/opencode/plugin/gocode-notify.js`. The hooks are merged, never clobbered — your existing hooks are preserved. |
 | **Pushes queue up while offline** then arrive later | Expected. Sends made while the server is unreachable are enqueued to `~/.gocode/outbox/` (size-capped, drop-oldest) and flushed best-effort on the next `send`. A missed "done" ping is acceptable; a blocked agent is not. |
-| **`npx @trygocode/notify` can't find the package** | Make sure you're online and using the scoped name exactly: `npx @trygocode/notify@latest setup`. Clear a stale npx cache with `npx clear-npx-cache` (or `rm -rf ~/.npm/_npx`) and retry. |
+| **`npx @trygocode/notify` can't find the package** | Until it's published to npm, run from a local tarball: `npm pack` in `tools/gocode-notify/`, then `npx ./gocode-notify-*.tgz <command>`. See [`docs/GOCODE_NOTIFY_MANUAL_STEPS.md`](../../docs/GOCODE_NOTIFY_MANUAL_STEPS.md). |
 | **Want it gone** | `gocode-notify uninstall` removes exactly the hook/MCP/rule entries this tool added (nothing else). Delete `~/.gocode/` to also drop the stored credentials, and revoke the key from the app's **"Connected agents"** screen. |
 
 **Logs & files.** Failures are appended to `~/.gocode/notify.log` (size-capped,
@@ -235,15 +305,15 @@ rotated to `notify.log.1`). Credentials live in `~/.gocode/credentials` (chmod
 `600`); non-secret prefs in `~/.gocode/config.json`; the offline queue in
 `~/.gocode/outbox/`.
 
-Found a bug or have a feature idea? Please
-[open an issue](https://github.com/joseph-lewis/gocode-notify/issues) — issues are
-welcome and usually get a reply within a day or two.
+For the device/secret/publish/deploy steps that are **not** part of this package
+(Android `google-services.json`, iOS APNs, server service-account, WSL rebuild,
+npm publish, real-device E2E), see
+[`docs/GOCODE_NOTIFY_MANUAL_STEPS.md`](../../docs/GOCODE_NOTIFY_MANUAL_STEPS.md).
 
 ## Develop
 
 ```bash
-git clone https://github.com/joseph-lewis/gocode-notify.git
-cd gocode-notify
+cd tools/gocode-notify
 npm install
 npm run build      # compile TypeScript -> dist/
 npm test           # builds, then runs node --test on dist/test/
@@ -258,9 +328,13 @@ Zero runtime dependencies beyond the MCP SDK (Node built-in `fetch`/`fs`/
 
 | Path | Purpose |
 |---|---|
-| `src/cli.ts` | `gocode-notify` bin entrypoint + command dispatcher |
+| `src/cli.ts` | `gocode-notify` bin entrypoint + command dispatcher (incl. `on-stop`, `config`) |
 | `src/setup.ts` | Installer orchestration (pair → detect → write configs) |
-| `src/claude.ts` / `src/cursor.ts` | Per-client config writers (hooks + MCP + rule/skill) |
+| `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 |
+| `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 |
+| `src/config.ts` | `config get\|set\|pull` — the dev-machine settings editor (server-synced) |
+| `src/settings.ts` | Canonical Notify settings schema + valid-key specs (mirrors the server + app) |
 | `snippets/ralph-homer.sh` | Opt-in loop completion/halt snippet (trigger C) |
 | `test/` | `node:test` smoke + unit tests |

package/dist/src/claude.js

@@ -36,26 +36,38 @@ export const MCP_SERVER_ENTRY = {
     args: ["-y", "@trygocode/notify", "mcp"],
 };
 /**
- * The hook command for each Claude Code event (PRD §5.3, verbatim shape). Every
- * command ends in `|| true` so a notification failure can never block the
- * agent's turn, and carries a per-session `--dedupe-key` so overlapping triggers
- * (e.g. Cursor `stop` + Claude `Stop`) coalesce server-side.
+ * The hook command for each Claude Code event (PRD §2.2, §5.3). Every command
+ * ends in `|| true` so a notification failure can never block the agent's turn,
+ * and carries a per-session `--dedupe-key` so overlapping triggers (e.g. Cursor
+ * `stop` + Claude `Stop`) coalesce server-side.
+ *
+ * `Stop` calls the `on-stop` DISPATCHER (PRD §2.2): it resolves settings and
+ * either runs the auto-push flow (which sends its own notification) or fires the
+ * plain `finished` ping — exactly one notification per turn. The pre-T-C6 form
+ * was `send --kind finished --source claude_code …`; both old and new commands
+ * contain the {@link HOOK_MARKERS} tokens, so old installs upgrade idempotently
+ * and uninstall cleanly. `Notification`/`SubagentStop` stay on the plain `send`
+ * (they are not turn-completion events and never auto-push).
  */
 export const CLAUDE_HOOK_COMMANDS = {
-    Stop: 'npx -y @trygocode/notify send --kind finished --source claude_code --dedupe-key "$CLAUDE_SESSION_ID-stop" || true',
+    Stop: 'npx -y @trygocode/notify on-stop --source claude_code --dedupe-key "$CLAUDE_SESSION_ID-stop" || true',
     Notification: 'npx -y @trygocode/notify send --kind awaiting_input --source claude_code --title "Agent needs you" --dedupe-key "$CLAUDE_SESSION_ID-notify" || true',
     SubagentStop: 'npx -y @trygocode/notify send --kind finished --source claude_code --title "Subagent done" --dedupe-key "$CLAUDE_SESSION_ID-subagent" || true',
 };
 /**
  * Substrings that together identify a hook command as OURS. Used for idempotent
  * merge (replace, don't duplicate) and for surgical uninstall (remove exactly
- * ours). A command must contain BOTH to be considered ours.
- *
- * `notify send` matches BOTH the current `npx -y @trygocode/notify send …`
- * form AND the legacy bare `gocode-notify send …` form, so upgrading from an
- * older install is detected and cleanly replaced rather than duplicated.
+ * ours). A command must contain BOTH to be considered ours. These tokens are
+ * present in BOTH the legacy `send --source claude_code` commands and the new
+ * `on-stop --source claude_code` Stop command, so they match old AND new
+ * installs (PRD §2.2).
  */
-const HOOK_MARKERS = ["notify send", "--source claude_code"];
+// Match OUR claude hook commands across ALL historical forms (current
+// `npx -y @trygocode/notify …`, published-0.1.2 `npx … notify send …`, and legacy
+// bare `gocode-notify …`). `--source claude_code` is the stable discriminator;
+// the name token matches whichever invocation style produced the entry.
+const HOOK_NAME_TOKENS = ["@trygocode/notify", "gocode-notify", "notify send"];
+const HOOK_SOURCE_TOKEN = "--source claude_code";
 /**
  * The on-demand skill written to `~/.claude/skills/gocode-notify/SKILL.md`
  * (PRD §5.5). The crucial content is the anti-double-ping rule: the automatic
@@ -123,9 +135,10 @@ async function writeJsonFile(file, value) {
 }
 /** True when a single hook ENTRY (`{ type, command }`) is one we wrote. */
 function isOurHookCommand(h) {
-    return (isRecord(h) &&
-        typeof h.command === "string" &&
-        HOOK_MARKERS.every((m) => h.command.includes(m)));
+    if (!isRecord(h) || typeof h.command !== "string")
+        return false;
+    const cmd = h.command;
+    return cmd.includes(HOOK_SOURCE_TOKEN) && HOOK_NAME_TOKENS.some((t) => cmd.includes(t));
 }
 /**
  * Strip OUR hook entries out of an event's group array, operating at the

package/dist/src/cli.js

@@ -18,6 +18,7 @@ import { serveStdio } from "./mcp.js";
 import { setup } from "./setup.js";
 import { uninstall } from "./uninstall.js";
 import { cmdConfig } from "./config.js";
+import { onStop } from "./on_stop.js";
 /** Subcommands the finished CLI will expose (see PRD §4.1). */
 export const COMMANDS = [
     "login",
@@ -28,6 +29,7 @@ export const COMMANDS = [
     "mcp",
     "uninstall",
     "config",
+    "on-stop",
 ];
 export function printHelp() {
     console.log([
@@ -46,6 +48,7 @@ export function printHelp() {
         "  mcp        Run as an MCP server over stdio",
         "  uninstall  Remove entries this tool added",
         "  config     Get/set Notify settings (get | set <key> <value> | pull)",
+        "  on-stop    End-of-turn dispatcher (auto-push or finished ping)",
         "",
         "  -h, --help       Show this help",
         "  -v, --version    Print the version",
@@ -375,6 +378,53 @@ export async function cmdMcp(args, deps = {}) {
     await serveStdio({ ...deps, serverFlag: flagString(flags, "server") });
     return 0;
 }
+/**
+ * Handle `gocode-notify on-stop --source S [--dedupe-key D] [--cwd DIR]
+ * [--server URL] [--dry-run] [--agent-driven]` (PRD §2.2). The single command
+ * the runtime stop hooks call: it resolves settings and either runs the
+ * auto-push flow (which sends its own notification) OR fires the plain
+ * `finished` ping — never both, so a turn yields exactly one notification.
+ *
+ * Like every hook entry it follows the PRD §0.5 non-blocking contract: it
+ * ALWAYS exits 0, even on a failed push/send, so a slow or failed notification
+ * can never block the agent's turn.
+ */
+export async function cmdOnStop(args, deps = {}) {
+    const flags = parseFlags(args);
+    const agent = isAgentDriven(flags);
+    const sink = deps.sink ?? stdoutSink;
+    const server = await resolveServerUrl(flagString(flags, "server"), deps);
+    const run = deps.onStopImpl ?? onStop;
+    const result = await run({
+        home: deps.home,
+        source: flagString(flags, "source"),
+        cwd: flagString(flags, "cwd"),
+        dedupeKey: flagString(flags, "dedupe-key"),
+        server,
+        dryRun: flagBool(flags, "dry-run"),
+        fetchImpl: deps.fetchImpl,
+        timeoutMs: deps.timeoutMs,
+        timestamp: deps.timestamp,
+    });
+    const delivered = result.mode === "push"
+        ? result.push?.notified === true
+        : result.mode === "send"
+            ? result.send?.ok === true
+            : undefined;
+    const detail = result.mode === "push"
+        ? `auto-push: ${result.push?.outcome ?? "unknown"}${delivered ? " (notified)" : ""}`
+        : result.mode === "dry-run-send"
+            ? "dry-run: would send finished (auto-push off)"
+            : `finished ${delivered ? "delivered" : "not delivered"}`;
+    if (agent) {
+        sink({ step: "on-stop", ok: true, detail });
+    }
+    else {
+        console.log(`✓ on-stop (${result.mode}): ${detail}`);
+    }
+    // PRD §0.5 / §4.4: a stop hook must NEVER block the turn — always exit 0.
+    return 0;
+}
 /** Synchronous dispatcher: help/version/unknown + not-yet-implemented commands. */
 export function run(argv) {
     const cmd = argv[0];
@@ -416,6 +466,8 @@ export async function runAsync(argv) {
         return cmdUninstall(argv.slice(1));
     if (cmd === "config")
         return cmdConfig(argv.slice(1));
+    if (cmd === "on-stop")
+        return cmdOnStop(argv.slice(1));
     return run(argv);
 }
 /**

package/dist/src/cursor.js

@@ -36,22 +36,34 @@ export const MCP_SERVER_ENTRY = {
     args: ["-y", "@trygocode/notify", "mcp"],
 };
 /**
- * The Cursor `stop` hook command (PRD §5.4, verbatim shape). Ends in `|| true`
- * so a notification failure can never block the agent's turn, and carries a
+ * The Cursor `stop` hook command (PRD §2.2, §5.4). Calls the `on-stop`
+ * DISPATCHER (not `send` directly): on-stop resolves settings and either runs
+ * the auto-push flow (which sends its own notification) or fires the plain
+ * `finished` ping — exactly one notification per turn. Ends in `|| true` so a
+ * notification/push failure can never block the agent's turn, and carries a
  * `--dedupe-key` so overlapping triggers (e.g. Cursor `stop` + Claude `Stop`)
  * coalesce server-side.
+ *
+ * The pre-T-C6 form was `gocode-notify send --kind finished --source cursor …`;
+ * both old and new commands contain the {@link HOOK_MARKERS} tokens, so an old
+ * install still upgrades idempotently and uninstalls cleanly (PRD §2.2).
  */
-export const CURSOR_STOP_COMMAND = "npx -y @trygocode/notify send --kind finished --source cursor --dedupe-key cursor-stop || true";
+export const CURSOR_STOP_COMMAND = "npx -y @trygocode/notify on-stop --source cursor --dedupe-key cursor-stop || true";
 /**
  * Substrings that together identify a `stop` hook entry as OURS. Used for
  * idempotent merge (replace, don't duplicate) and for surgical uninstall (remove
- * exactly ours). A command must contain BOTH to be considered ours.
- *
- * `notify send` matches BOTH the current `npx -y @trygocode/notify send …`
- * form AND the legacy bare `gocode-notify send …` form, so an upgrade from an
- * older install is detected and cleanly replaced rather than duplicated.
+ * exactly ours). A command must contain BOTH to be considered ours. These tokens
+ * are present in BOTH the legacy `send --source cursor` command and the new
+ * `on-stop --source cursor` command, so they match old AND new installs (§2.2).
  */
-const HOOK_MARKERS = ["notify send", "--source cursor"];
+// Match OUR cursor stop hook across ALL historical command forms so upgrades
+// replace (never duplicate) and uninstall stays surgical. The `--source cursor`
+// token is the stable discriminator; the first token matches whichever invocation
+// style produced the entry: the current `npx -y @trygocode/notify …`, the
+// published-0.1.2 `npx … notify send …`, or the legacy bare `gocode-notify …`.
+// A command is ours if it has `--source cursor` AND any of these name tokens.
+const HOOK_NAME_TOKENS = ["@trygocode/notify", "gocode-notify", "notify send"];
+const HOOK_SOURCE_TOKEN = "--source cursor";
 /**
  * The on-demand rule written to `~/.cursor/rules/gocode-notify.md` (PRD §5.5).
  * The crucial content is the anti-double-ping rule: the automatic pings are
@@ -125,9 +137,10 @@ async function writeJsonFile(file, value) {
 }
 /** True when a single `stop` hook entry (`{ command }`) is one we wrote. */
 function isOurStopHook(h) {
-    return (isRecord(h) &&
-        typeof h.command === "string" &&
-        HOOK_MARKERS.every((m) => h.command.includes(m)));
+    if (!isRecord(h) || typeof h.command !== "string")
+        return false;
+    const cmd = h.command;
+    return cmd.includes(HOOK_SOURCE_TOKEN) && HOOK_NAME_TOKENS.some((t) => cmd.includes(t));
 }
 /**
  * Strip OUR entries out of the `stop` array. Returns the cleaned array plus

package/dist/src/mcp.js

@@ -19,35 +19,6 @@ import { send, isNotifyKind, NOTIFY_KINDS, } from "./send.js";
 import { gatherStatus } from "./status.js";
 /** Server identity advertised in the MCP `initialize` handshake. */
 export const SERVER_NAME = "gocode-notify";
-/**
- * Public website for this MCP server, surfaced in the MCP `initialize`
- * handshake (`Implementation.websiteUrl`, SEP-973). Clients that support it
- * (MCP Inspector today; more clients over time) link the server to its docs.
- */
-export const SERVER_WEBSITE_URL = "https://github.com/joseph-lewis/gocode-notify";
-/**
- * Icons advertised in the MCP handshake (`Implementation.icons`, SEP-973) so
- * clients can show the GoCode mark next to this server in their UI. Served from
- * the public repo's `assets/` over GitHub's raw CDN so there's nothing to host.
- *
- * NOTE: as of 2026, Cursor does not yet RENDER custom MCP server icons (it uses
- * hardcoded marks for a few popular servers), so this stays invisible there for
- * now — but it already shows in MCP Inspector and other spec-compliant clients,
- * and will light up in Cursor automatically once it adds rendering. Cheap +
- * future-proof; no behaviour depends on it.
- */
-export const SERVER_ICONS = [
-    {
-        src: "https://raw.githubusercontent.com/joseph-lewis/gocode-notify/main/assets/icon-128.png",
-        mimeType: "image/png",
-        sizes: ["128x128"],
-    },
-    {
-        src: "https://raw.githubusercontent.com/joseph-lewis/gocode-notify/main/assets/icon-512.png",
-        mimeType: "image/png",
-        sizes: ["512x512"],
-    },
-];
 /** Tool name an agent calls to send an on-demand push. */
 export const NOTIFY_TOOL = "gocode_notify";
 /** Tool name an agent calls to self-diagnose pairing/reachability. */
@@ -177,15 +148,7 @@ export async function handleStatus(deps = {}) {
  * drive it over an in-memory transport.
  */
 export function createMcpServer(deps = {}) {
-    const server = new Server({
-        name: SERVER_NAME,
-        version: VERSION,
-        // SEP-973 server metadata: icons + website for client UIs that support it
-        // (MCP Inspector now; more clients over time). Ignored by clients that
-        // don't read them.
-        icons: [...SERVER_ICONS],
-        websiteUrl: SERVER_WEBSITE_URL,
-    }, { capabilities: { tools: {} } });
+    const server = new Server({ name: SERVER_NAME, version: VERSION }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...TOOLS] }));
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const { name, arguments: args } = req.params;