omni-notify-mcp 1.3.30 → 1.3.285

package/README.md

@@ -5,150 +5,229 @@
 <h1 align="center">BullseyeNotify · <code>omni-notify-mcp</code></h1>
 
 <p align="center">
-  A local notification bus for AI agents. One HTTP server owns the channels, the
-  routing policy and the inbound message queue; a thin stdio MCP bridge exposes it
-  to Claude Code, Cursor, Copilot and any other MCP host; a VS Code extension frames
-  the config UI in the editor.
+  Your coding agent, on your machine, from anywhere. BullseyeNotify runs a full interactive Claude Code, Codex
+  or Copilot CLI and mirrors that one real session in your browser — a manager of remote CLI sessions, reachable
+  from your phone, ChatGPT, claude.ai, Telegram, Slack or email behind a passkey or OAuth sign-in and your own tunnel.
+  It reaches you back too: you tell your AI what you want, and it notifies, asks and waits through this server.
+  Desktop, Telegram, Slack, ntfy, Discord, Teams and SMS are configured in one file, and Do Not Disturb
+  and idle detection decide what actually gets through.
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/omni-notify-mcp"><img src="https://img.shields.io/npm/v/omni-notify-mcp.svg" alt="npm"></a>
+  <a href="https://raw.githubusercontent.com/menih/ext-listing-assets/main/bullseye-notify/10-chat.png"><img src="https://raw.githubusercontent.com/menih/ext-listing-assets/main/bullseye-notify/10-chat.png" width="620" alt="A conversation in BullseyeNotify's web page: the agent's answer drawn as Markdown with a real table, and the measured times"></a>
+</p>
+
+<p align="center">
+  <a href="https://raw.githubusercontent.com/menih/ext-listing-assets/main/bullseye-notify/09b-live-cli.png"><img src="https://raw.githubusercontent.com/menih/ext-listing-assets/main/bullseye-notify/09b-live-cli.png" width="300" alt="A real agent CLI running on the machine, mirrored in the browser"></a>
+  <a href="https://raw.githubusercontent.com/menih/ext-listing-assets/main/bullseye-notify/08-agent-panel.png"><img src="https://raw.githubusercontent.com/menih/ext-listing-assets/main/bullseye-notify/08-agent-panel.png" width="200" alt="The panel with Start, Stop and Restart"></a>
+  <a href="https://raw.githubusercontent.com/menih/ext-listing-assets/main/bullseye-notify/11-chat-phone.png"><img src="https://raw.githubusercontent.com/menih/ext-listing-assets/main/bullseye-notify/11-chat-phone.png" width="140" alt="The chat on a phone"></a>
+</p>
+
+The extension README lists the 13 `agent_*` tools of the `bn` MCP, the 10 tools of the `notify` MCP, every door in, the sign-in methods and the panel's server controls.
+
+<p align="center">
   <a href="https://marketplace.visualstudio.com/items?itemName=menihillel.bullseye-notify"><img src="https://img.shields.io/visual-studio-marketplace/v/menihillel.bullseye-notify?label=marketplace" alt="VS Code Marketplace"></a>
   <img src="https://img.shields.io/badge/license-MIT-4ea3ff.svg" alt="MIT license">
   <img src="https://img.shields.io/badge/node-%3E%3D18-4ea3ff.svg" alt="Node 18+">
 </p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/menih/BullseyeNotif/main/assets/screenshots/main-ui.png" width="900" alt="Config UI — delivery channels and system policies side by side, with the activity log below">
+  <a href="https://raw.githubusercontent.com/menih/ext-listing-assets/main/bullseye-notify/01-config-panel.png"><img src="https://raw.githubusercontent.com/menih/ext-listing-assets/main/bullseye-notify/01-config-panel.png" width="900" alt="The config panel — every channel and its credentials, Do Not Disturb and quiet hours, idle and the master mute"></a>
 </p>
 
 ---
 
-## The two processes
+## A manager of remote CLI sessions
 
-| Process | Entry | What it owns |
-|---|---|---|
-| **UI/HTTP server** | `dist/ui/server.js` (bin `omni-notify-ui`) | Every channel implementation, the routing policy (DND / idle / mute), the inbound inbox, the Telegram long-poll listener, the Slack channel poller, the built-in ntfy server, the web config UI, and — when `ENABLE_MCP=1` — the Streamable-HTTP `/mcp` endpoint. Listens on `0.0.0.0:3737` by default. |
-| **stdio MCP bridge** | `dist/index.js` (bin `omni-notify-mcp`) | A stateless proxy. Auto-spawns the server if `:3737` isn't answering, opens one persistent `/mcp` session, forwards every tool call to it, subscribes to `/api/inbox/stream` and re-emits each message as a `notifications/claude/channel` event. Holds no config and no queue. |
+Beyond notifications, BullseyeNotify runs a full interactive agent CLI on your machine and mirrors it to the browser. The gateway's `/mcp` door carries the `agent_*` tools, and the same host serves `GET /` — BN's one page, where you open a real `claude`, `codex` or `copilot` CLI (drawn through xterm.js over a node-pty worker in Node), attach, reattach and close it, and read the message conversations the REST, MCP, Telegram and email doors create. The browser shows that one CLI and adds nothing of its own; there is no second UI and no second way to start a session. An MCP caller can attach to a session's live stream — the agent's thinking and output as they arrive — instead of waiting for the finished reply.
+
+## One process, one door
 
-The VS Code extension (`vscode-extension/`) is a third, optional face: it starts the
-server if needed and renders `http://localhost:3737/` inside a webview.
+`omni-notify-mcp` **is** the notification server. In the shipped VS Code extension one
+copy of it runs at login and serves a single door on loopback
+(`http://127.0.0.1:7475/mcp`); Claude Code and VS Code / Copilot Chat are pointed at
+that door, so neither spawns a child per session. The same source is also a plain stdio
+server for anything that can only spawn one:
 
-> **Build note.** `package.json` is deliberately untracked in this repo (see
-> `.gitignore`), so the dependency list, the `bin` map, the version and the extension
-> manifest are not in git. The published package declares `build` as
-> `tsc && tsc -p ui/tsconfig.json` and `test` as `npm run build && node --test tests/*.test.mjs`.
+```bash
+node dist/index.js        # the stdio entry; a stdio host spawns this and holds its pipe
+```
+
+The config is a plain file (below), and the editor-side panel that edits it lives in
+the VS Code extension. A stdio host's copy exits when its host goes away; the resident
+process the extension starts does not — it belongs to no window and outlives them all.
+
+> **Build note.** `package.json` is deliberately tracked here (see `.gitignore`), so
+> `bin`, `main` and the build scripts are all in git. The published package declares
+> `build` as `tsc` and `test` as `npm run build && node tests/run-tests.js`.
 
 ## Quick start
 
 ```bash
 npm install
 npm run build
-ENABLE_MCP=1 node dist/ui/server.js     # or: ./notify-ui.sh (no MCP)
 ```
 
-Open <http://localhost:3737>, enable the channels you want, hit the per-channel
-**Test** button. Config is written to `~/.notify-mcp/config.json` and re-read on
-every notification — no restart after a settings change.
+Then register the server with an MCP host. Install the VS Code extension from the
+marketplace and it does the wiring for you — it ships the server inside the `.vsix`,
+starts one resident copy of it at login from a path mirrored outside the versioned
+install folder, and points Claude Code and VS Code / Copilot Chat at the door that copy
+serves:
 
-Register the bridge with an MCP host:
+```json
+{
+  "mcpServers": {
+    "notify": { "type": "http", "url": "http://127.0.0.1:7475/mcp" }
+  }
+}
+```
+
+A host that can only spawn a stdio server takes the mirrored bundle instead, starting
+its own child per session:
 
 ```json
 {
   "mcpServers": {
-    "notify": { "type": "stdio", "command": "npx", "args": ["-y", "omni-notify-mcp"] }
+    "notify": { "type": "stdio", "command": "node", "args": ["<globalStorage>/dist/index.mjs"] }
   }
 }
 ```
 
-VS Code / Copilot use `.vscode/mcp.json` with a `servers` key instead of
-`mcpServers`; the bundled help page at `http://localhost:3737/help.html` has the exact
-snippet for Claude Code, Cursor, VS Code, Claude Desktop, Windsurf, Zed and generic
-clients.
+## MCP wiring
+
+The extension wires the two hosts whose config files it may write, re-checked on every
+window start so a machine registered by an older release converges on its own:
+
+| Host | Where it registers | Key |
+|---|---|---|
+| **Claude Code** | `~/.claude.json` | `mcpServers.notify` |
+| **VS Code / GitHub Copilot Chat** | the extension's `contributes.mcpServerDefinitionProviders` **and** the workspace's `.vscode/mcp.json` | `servers.notify` |
 
-## MCP tools
+Both point at the door the copy bundled inside the extension serves. Any other host is
+wired by hand, with either entry from *Quick start* — for **Codex** that is
+`~/.codex/config.toml` under `[mcp_servers.notify]`, `command`/`args` naming the mirrored
+bundle. A `notify` entry that differs from ours is yours and is left untouched; a build
+that bundled no server registers nothing and says so.
 
-Eight tools over HTTP, nine over stdio. The agent never names a channel — routing is
+## Tools
+
+Ten tools over the one notify server. The agent never names a channel — routing is
 entirely server-side.
 
 | Tool | Arguments | Behaviour |
 |---|---|---|
-| `notify` | `message`, `priority` = `low`\|`normal`\|`high` | Fan out per the routing table below. Response states `outcome=` with the `attempted` and `delivered` channels plus any per-channel error, and carries any queued inbox messages for this session. |
-| `ask` | `question`, `timeout_seconds` (30–3600, default 300) | Sends the question to Telegram (every configured chat id) and email (with a one-shot `/reply/:token` web page), then **blocks** until a reply lands or the timeout throws. |
-| `poll` | — | Drains queued inbox messages for this session's tag; returns `inbox:empty` when there are none. |
-| `wait_for_inbox` | `timeout_seconds` (5–55, default 50) | Parks a waiter and returns the moment a matching message arrives, as a tool *result*. Returns already-queued messages immediately without parking. |
-| `get_idle_seconds` | — | Seconds since the last OS keyboard/mouse input, or `-1` where unsupported. Drains the inbox as a side effect. |
-| `get_idle_config` | — | `{ enabled, thresholdSeconds, alwaysDesktopWhenActive }`. Drains the inbox. |
-| `get_dnd_status` | — | `{ active, reason }` where reason is `disabled` (master mute or this client disabled), `manual`, `schedule` or `off`. Drains the inbox. |
+| `notify` | `message` (≤5000), `priority` = `low`\|`normal`\|`high` | Fan out per the routing table below. The result states `outcome=` with the `attempted` and `delivered` channels, and carries any queued inbox messages for this session. |
+| `ask` | `question` (≤500), `timeout_seconds` (30–3600, default 300) | Sends the question over Telegram and **blocks** until you answer. The wait is clamped to the caller's own transport limit, so it returns `NO REPLY YET` and leaves the question open rather than reporting it as ignored; the answer arrives in the inbox. |
+| `poll` | — | Drains queued inbox messages for this session; returns `inbox:empty` when there are none. |
+| `wait_for_inbox` | `timeout_seconds` (5–55, default 50) | Blocks and returns the moment you type, as a tool *result* — the delivery path that works in every MCP client. Returns already-queued messages immediately. |
+| `get_idle_seconds` | — | How long since the last keyboard/mouse input, as one of two DIFFERENT answers: `idle: measured N seconds …`, or `idle: could not measure — user activity unknown, so activity gating is skipped`. |
+| `get_idle_config` | — | `{ enabled, thresholdSeconds, alwaysDesktopWhenActive }`. |
+| `get_delivery_status` | — | `{ process, healthy, channels, carriage, reason }` from real transport readings, not from config or from the process being alive. `healthy` is true only when every enabled channel has been MEASURED able to carry. |
+| `get_dnd_status` | — | `{ active, reason }` where reason is `disabled`, `manual`, `schedule` or `off`. |
 | `update_instructions` | `instructions` (≤4000), `target` = `global`\|`project` | Rewrites a marker-delimited block in `~/.claude/CLAUDE.md` (global) or `./.claude/CLAUDE.md` (project). |
-| `reply` *(stdio bridge only)* | `message` (≤2000), `priority` | The Claude Code Channels return path. Prefixes the bridge's session tag and routes through `notify`. |
+| `reply` | `message` (≤2000) | The return path for your most recent channel message, routed back through `notify` so it lands on whichever channel you are reading. |
+
+**Message size and chunking.** `notify` accepts up to 5000 characters and splits
+anything over 500 into numbered `(1/N) …` chunks (word-aware where a break lands past
+60 % of the budget), delivered in order. The agent sends the whole message in one call
+and never truncates.
 
-**Message size and chunking.** The HTTP server caps `notify.message` at 500
-characters and rejects anything longer. The stdio bridge accepts up to 5000, splits it
-in `src/chunk.ts` into `(1/N) …` chunks of ≤500 (word-aware where a break lands past
-60 % of the budget), and delivers them in order — so chunking exists **only on the
-bridge path**. A bridge caller gets back either `Delivered as N chunks (M chars).` or a
-count of how many chunks reached no channel and what the server said.
+## Timing an answer
+
+Every answer in an agent conversation, and every turn that failed, carries a `timing`
+object, and every figure in it was measured on **BN's own clock** — the clock of the BN
+process that stored the event. Both doors return the same names.
+
+| Field | What it is |
+|---|---|
+| `bnMs` | The end-to-end elapsed time of a reply: the milliseconds from the request arriving at BN's door to the answer being stored — the door's own `receivedMs` plus `totalMs`. It is never the agent's time; that is `agentMs`. |
+| `queuedMs` | The part of `bnMs` the message waited for a free slot or the turn ahead — the stored queue row's own measured span, from the message being stored to the turn starting. Present exactly when the turn queued and then started; never a subtraction made by a reader. |
+| `queued` | Whether the turn stood in line at all. `false` is the store's own statement that no queue line was written for that turn — it never stood in line; absent means no queue figure was ever stored for it, which is neither. |
+| `totalMs` | BN's own total: the part from the message being stored in the conversation's log to the answer being stored. It sits inside `bnMs` and is never relabelled as the agent's time. |
+| `agentMs` | The agent CLI's own share — the part of the turn the agent itself worked, without BN's time around it. Absent on a failure BN stored outside a turn of its own: no agent share was measured there, so none is printed. |
+| `rows` | The turn layer by layer, each with its own `ms`; a row marked `part` sits inside the row above it and is never added to the total. |
+| `receivedMs` | On the message: the door's own wait, the request arriving → the message stored. A REST send answers it, and it is the first half of every answer's `bnMs`. |
+| `waitedMs` | On the call that hands a turn's end to its caller: how long that `agent_wait` or `agent_prompt` call held, measured on BN's own clock and written on its `returned` line and returned by `agent_prompt`. |
+| `servedAt` | On a REST events read: when BN served it, so a page tells BN's time from its own. |
+
+A reply's time is read as three separate figures and never as one number: the end-to-end
+`bnMs`, the `queuedMs` that was waiting, and the `agentMs` that was the agent working.
+The arithmetic holds on every turn: `bnMs = receivedMs + totalMs`,
+`bnMs >= totalMs >= agentMs >= 0` wherever `agentMs` is present, and
+`queuedMs` is the span of the queue row inside `totalMs` — so on a turn that queued and
+started, the queued figure and the row a reader sees are the same number. `agent_prompt` returns
+the ending event's `timing` beside the answer text; `agent_wait` returns the events
+themselves, each with its own. `GET /v1/conversations/{id}` carries no second copy of a
+turn's time — the events read is the one way to learn it.
+
+**Where the figures stop.** These are the three edges of the measurement, and each one
+prints nothing rather than a guess. A message stored before this change carries no
+`receivedMs`, so its answer has no `bnMs` — there is no measured door wait to add. A
+failure BN stores for a message it holds no request for is written without a `timing` at
+all. A turn that crossed a BN restart reads the wait before it off the stored times the
+earlier BN process wrote, so that one row is that process's wall clock, named as such in
+its own words.
+
+**What BN cannot see.** Voice transcription, the ChatGPT dispatch, the plugin's own
+transit, the client's network and the page's render all happen outside BN's process, so
+the rows name them `UNMEASURED` and give them no figure. None of them is ever worked out
+by subtracting BN's own numbers from a total: a figure BN did not measure is never
+printed as though it had.
 
 ## Delivery routing
 
-`sendWithRouting` in `ui/messaging/notificationEngine.ts` is the single chokepoint.
-Three suppressions run before it, in order: master mute (`muteAll`) drops everything
+Suppression runs first, in order: **master mute** (`muteAll`) drops everything
 including `high`; a client listed in `disabledClients` is dropped by client id; then
-DND drops everything below `high`.
-
-The **desktop-only** mode kicks in when the web UI reported itself visible in the last
-30 s, or when idle gating is on, no Telegram conversation has been active in the last
-5 minutes, and OS idle time is under the threshold.
-
-> With `idle.alwaysDesktopWhenActive: false` the desktop is held back too while the user
-> is active, so only Slack is attempted. When Slack is off nothing is sent, and the reply
-> says `outcome=blocked`, as it does under DND, never `outcome=failed`.
-
-| Channel | `low` | `normal` | `high` | Under desktop-only |
-|---|---|---|---|---|
-| desktop | — | ✓ | ✓ | ✓ |
-| telegram | — | ✓ | ✓ | — |
-| email | ✓ | ✓ | ✓ | — |
-| ntfy | ✓ | ✓ | ✓ | — |
-| discord | ✓ | ✓ | ✓ | — |
-| teams | ✓ | ✓ | ✓ | — |
-| slack | ✓ | ✓ | ✓ | **✓ — exempt from idle gating** |
-| sms | — | — | ✓ | — |
-
-`priority: 'high'` bypasses DND and idle gating both. Per-channel failures are
-collected, never thrown: the tool response lists what was delivered and what errored.
+**Do Not Disturb** holds everything, `high` included — nothing reaches you until it
+lifts. A deliberate hold is a choice and never wears the same face as a defect.
+
+Then **idle gating**: while you are at the keyboard, a non-`high` message is held back
+from the remote channels and, with `idle.alwaysDesktopWhenActive: true`, still shows as
+a silent desktop toast. Slack is deliberately exempt so a channel log stays complete;
+when `alwaysDesktopWhenActive: false` the desktop is held back too, so only that Slack
+log is used. `priority: 'high'` bypasses idle gating only — DND holds it too.
+
+| Channel | `low` | `normal` | `high` |
+|---|---|---|---|
+| desktop | — | ✓ | ✓ |
+| telegram | — | ✓ | ✓ |
+| ntfy | ✓ | ✓ | ✓ |
+| discord | ✓ | ✓ | ✓ |
+| slack | ✓ | ✓ | ✓ |
+| teams | ✓ | ✓ | ✓ |
+| sms | — | — | ✓ |
+
+Per-channel failures are collected, never thrown: the tool result lists what was
+delivered and what errored.
 
 ## Channels
 
 Every channel is off until enabled, and a channel whose credentials are incomplete is
-skipped by the `enable*` predicates in `ui/server.ts` even when `enabled: true`.
+skipped even when `enabled: true`. There is **no email channel** and **no built-in
+ntfy server** — ntfy is an external server you name.
 
 | Channel | Config key and fields | Transport |
 |---|---|---|
-| **Desktop** | `desktop` — `enabled`, `sound`, `tts`, `ttsVoice` | `node-notifier` toast titled *Claude Notify*. On Windows the toast sound is unreliable, so a PowerShell `SystemSounds::Asterisk` is fired alongside it. With `tts: true` the body is synthesised through `msedge-tts` (default voice `en-US-AndrewMultilingualNeural`) and played via MediaPlayer / `afplay` / `aplay`. |
-| **Telegram** | `telegram` — `enabled`, `token`, `chatIds[]` | `sendMessage` per chat id. When the last inbound message came from that same chat, the notification is sent as a threaded reply. Also the inbound listener (see below). |
-| **Email** | `email` — `enabled`, `to`, plus either Gmail OAuth (`clientId`, `clientSecret`, `refreshToken`, `accessToken`, `connectedEmail`) or SMTP (`host`, `port` 587, `secure` false, `user`, `pass`) | `nodemailer`; subject *Claude Notify*. OAuth wins when a refresh token is present. `ask` sends HTML with a **Reply to Claude** button pointing at `http://<lan-ip>:3737/reply/<token>`. |
-| **SMS** | `sms` — `enabled`, `accessKeyId`, `secretAccessKey`, `region`, `originationNumber`, `to[]` | AWS End User Messaging (`@aws-sdk/client-pinpoint-sms-voice-v2`, `SendTextMessage`), one call per destination, numbers normalised to E.164. `high` priority only. |
-| **ntfy** | `ntfy` — `enabled`, `topic`, `serverUrl` (display only), `token` | **This server *is* the ntfy server.** It implements the publish/subscribe wire protocol at `/:topic/sse`, `/:topic/json` and `PUT`/`POST /:topic`, and a notification fans out to whoever is subscribed to that topic *on this server*. Point the ntfy mobile app at this host. Sending with zero subscribers is an error, not a silent drop. |
-| **Discord** | `discord` — `enabled`, `webhookUrl`, `username`, `clientId`, `clientSecret`, `channelName` | Webhook embed, colour-coded by priority. `GET /auth/discord/start` runs a one-click OAuth flow (`webhook.incoming` scope) that returns a ready-made channel webhook. |
-| **Slack** | `slack` — `enabled`, `webhookUrl`, `botToken`, `channels[]`, `clientId`, `clientSecret`, `team` | With a bot token **and** channels, one `chat.postMessage` per channel; otherwise the single incoming webhook. `GET /auth/slack/start` runs OAuth for `channels:read,groups:read,channels:history,groups:history,chat:write,chat:write.public`, so the minted token also serves the Slack bus poller. When `slack.botToken` is blank the token from `notify-secrets.json` / `SLACK_BOT_TOKEN` is reused. |
+| **Desktop** | `desktop` — `enabled`, `tts`, `ttsVoice` | `node-notifier` toast titled *Claude Notify*, always silent. With `tts: true` the body is read aloud through `msedge-tts` — no API key. |
+| **Telegram** | `telegram` — `enabled`, `token`, `chatIds[]` | `sendMessage` per chat id; also the inbound listener. The bot answers in-thread, naming whether your message was routed, broadcast or queued. |
+| **SMS** | `sms` — `enabled`, `accessKeyId`, `secretAccessKey`, `region`, `originationNumber`, `to[]` | AWS End User Messaging (`SendTextMessage`), one call per destination, numbers normalised to E.164. `high` priority only. |
+| **ntfy** | `ntfy` — `enabled`, `topic`, `serverUrl`, `token` | HTTP POST to an external ntfy server you name (`ntfy.serverUrl`, e.g. a self-hosted one or `https://ntfy.sh`), so the ntfy mobile app gets the push. |
+| **Discord** | `discord` — `enabled`, `webhookUrl`, `username` | Webhook embed, colour-coded by priority. |
+| **Slack** | `slack` — `enabled`, `webhookUrl`, `botToken`, `channels[]` | With a bot token **and** channels, one `chat.postMessage` per channel; otherwise the single incoming webhook. The same token serves the Slack bus poller. |
 | **Teams** | `teams` — `enabled`, `webhookUrl` | Adaptive Card v1.2 posted to a Teams *Workflows* webhook. |
 
 ## Configuration
 
-`~/.notify-mcp/config.json`, overridable with `NOTIFY_MCP_CONFIG_DIR`. The UI writes
-it; secrets are replaced with `••••••••` on read and a masked value posted back is
-restored from the on-disk copy rather than overwriting it. Legacy single-destination
-fields are migrated on load: `telegram.chatId` → `chatIds[]`, `sms.to` string →
-array, and the dead Twilio fields (`accountSid`, `authToken`, `from`) are deleted.
+`~/.notify-mcp/config.json`, overridable with `NOTIFY_MCP_CONFIG_DIR`. It is a plain
+file, written by hand or by the extension's config panel, and re-read on every
+notification — no restart after a settings change.
 
 ```json
 {
   "muteAll": false,
   "disabledClients": [],
   "clientAliases": {},
-  "desktop": { "enabled": true, "sound": true, "tts": false },
+  "desktop": { "enabled": true },
   "telegram": { "enabled": true, "token": "BOT_TOKEN", "chatIds": ["123456789"] },
   "sms": {
     "enabled": false,
@@ -156,11 +235,6 @@ array, and the dead Twilio fields (`accountSid`, `authToken`, `from`) are delete
     "region": "us-east-1", "originationNumber": "+15550000000",
     "to": ["+15550000001"]
   },
-  "email": {
-    "enabled": true, "to": "you@gmail.com",
-    "host": "smtp.gmail.com", "port": 587, "secure": false,
-    "user": "you@gmail.com", "pass": "GMAIL_APP_PASSWORD"
-  },
   "ntfy":    { "enabled": false, "topic": "", "serverUrl": "" },
   "discord": { "enabled": false, "webhookUrl": "", "username": "Claude Notify" },
   "slack":   { "enabled": false, "webhookUrl": "", "botToken": "", "channels": [] },
@@ -173,59 +247,23 @@ array, and the dead Twilio fields (`accountSid`, `authToken`, `from`) are delete
 }
 ```
 
-`notify-secrets.json` at the repo root is a second, optional source: values under keys
+A partial file is a legitimate config — a section it omits is created on load, and
+legacy single-destination fields are migrated (`telegram.chatId` → `chatIds[]`).
+
+**Secrets.** `notify-secrets.json` is a second, optional source: values under keys
 ending in `_b64` are base64-decoded at load, and on startup any credential it holds is
 copied into **empty** fields of `config.json` (never over a value you already set).
-See `config.example.json` for a hand-written starting point.
-
-**This only works if the running server can actually find that file.** The lookup path is
-`NOTIFY_MCP_SECRETS_PATH`, defaulting to `<CONFIG_DIR>/notify-secrets.json` — and `CONFIG_DIR`
-defaults to `~/.notify-mcp`, a **home-relative** path, not the repo root. A server started via
-`npx` or the VS Code extension runs from an npm cache directory with no relationship to any git
-checkout, so simply having `notify-secrets.json` committed at the repo root does nothing on its
-own (story #438: this sat silently broken for months — every channel stayed disabled and every
-`notify` reached nobody, because nothing ever pointed the server at the repo file). Set
-`NOTIFY_MCP_SECRETS_PATH` to the repo's `notify-secrets.json` as a **persistent environment
-variable** on each machine that has a checkout (`setx NOTIFY_MCP_SECRETS_PATH "C:\path\to\BullseyeNotif\notify-secrets.json"`
-on Windows, or export it from your shell profile elsewhere) — set once, it survives reboots and
-every future server restart on that machine picks it up. Check `GET /api/config` after a restart:
-a channel listed in `notify-secrets.json` with `enabled: true` and its required fields populated
-should show `enabled: true` there too — if it still shows `false`, the file was not found.
-
-## Inbound — the inbox
-
-Messages arriving *from* the user (Telegram reply, Slack channel post,
-`POST /api/agent/inbox/inject`, Slack Events API) land in one queue and are delivered
-through whichever path is available:
-
-1. **Parked long-poll waiters** get first refusal — `wait_for_inbox` or
-   `GET /api/agent/inbox/wait`, delivered as a tool/HTTP result. Message is handed to
-   the waiters and not queued.
-2. **SSE broadcast** to every `/api/inbox/stream` subscriber whose tag matches. The
-   stdio bridge is such a subscriber and re-emits each message as a
-   `notifications/claude/channel` event, which Claude Code (CLI, launched with
-   `--channels`) surfaces as a synthetic turn.
-3. **File drop** at `~/.notify-mcp/inbox/<iso-ts>[.<tag>].md`, reaped after 24 h. The
-   Slack-origin drop embeds the exact `curl` needed to answer in-channel.
-   `.claude/notify-inbox-drain.sh` is the consumer shipped here: it is wired into
-   `SessionStart`, `UserPromptSubmit` and `Stop`, matches this session's tag, deletes
-   each file as it reads it, and returns the text as `additionalContext` (or as a
-   `decision: "block"` reason on `Stop`, which is what lets a message reach an agent
-   mid-loop). It deliberately no-ops on `PreToolUse`/`PostToolUse`, where Claude Code
-   discards hook output — draining there would delete a message without delivering it.
-
-**Tags.** A session declares one via `/mcp?tag=<name>` or `/api/inbox/stream?tag=<name>`.
-A user message prefixed `@<tag> ` is routed to that tag only; everything else
-broadcasts. The bridge derives its own tag as
-`<hostname>-<project>` where `<project>` is `NOTIFY_MCP_TAG`, else the nearest
-meaningful folder walking up from `CLAUDE_PROJECT_DIR` (generic names like `claude`,
-`code`, `src`, `dist`, `system32` are skipped). When neither variable is set — the VS
-Code extension case — a 6-character hash of `CLAUDE_CODE_SESSION_ID` is appended so two
-windows sharing a working directory stay distinct. Subagents inherit their parent's
-session id, so `/api/clients` folds them into the parent's panel.
-
-Telegram acknowledges every inbound message in-thread, naming what it did:
-routed to `@tag`, broadcast to *n* listeners, or queued because nobody is connected.
+The lookup path is `NOTIFY_MCP_SECRETS_PATH`, defaulting to
+`<CONFIG_DIR>/notify-secrets.json` — a **home-relative** path, not the repo root. See
+`config.example.json` for a hand-written starting point.
+
+## Tags — many agents, one server
+
+Every session declares a tag — host plus project, or an explicit `NOTIFY_MCP_TAG`.
+Untagged messages broadcast to all connected clients; `@<tag> …` goes to exactly one.
+In the config file, `clientAliases` gives a tag a readable name and `disabledClients`
+silences one agent. Subagents inherit their parent's session id, so they fold into the
+parent's inbox.
 
 ## Slack bus
 
@@ -233,85 +271,39 @@ A single shared Slack channel works as a cross-machine bus: the server polls
 `conversations.history` every 2 s, ingests genuine human messages only, answers
 `clients` / `help` in-channel itself, and routes `@<name> …` / `#<n> …` to the matching
 connected client. Full architecture, addressing rules and operating notes:
-[`docs/SLACK-BUS.md`](docs/SLACK-BUS.md).
-
-## Web UI
+[`../docs/BullseyeNotif/SLACK-BUS.md`](../docs/BullseyeNotif/SLACK-BUS.md).
 
-One page at `:3737`, dark, no build step. A master-mute bar on top; a **Delivery
-channels** column (desktop, email, telegram, sms, ntfy, discord, slack, teams — each a
-collapsible card with a status badge, an enable toggle, a **Test** button and inline
-setup instructions); a **System policies** column (Do Not Disturb manual + scheduled
-quiet hours with per-day checkboxes; idle gating threshold and the
-always-play-desktop-sound toggle). Below them a collapsible panel with two tabs: the
-live activity log (SSE, last 500 lines replayed on connect, direction-marked `→ ← ·`)
-and **Clients**, which lists every connected session with its panel number and lets you
-rename, disable or force-reconnect one. `help.html` is the copy-paste setup page.
+## The status bell (VS Code extension)
 
-## HTTP endpoints
+A status-bar bell that never shows green over a channel that carries nothing, refreshed
+every 10 s. Every state has its own icon and colour, so a defect can never wear the
+costume of a choice:
 
-| Path | Purpose |
-|---|---|
-| `ALL /mcp[?tag=&hsid=]` | Streamable-HTTP MCP transport. `404 mcp_disabled` unless `ENABLE_MCP=1`. An unknown session id on a fresh `initialize` is adopted (survives a server restart); on any other request it returns 404 so the client reinitialises. |
-| `GET /api/inbox/stream[?tag=]` | SSE push of inbound user messages, 20 s keepalive comments. |
-| `GET /api/logs` | SSE activity log. |
-| `GET/POST /api/config` | Read (masked) / merge-write the config. |
-| `GET/POST /api/mute` | Master kill switch. |
-| `POST /api/window/register` | Extension → server: `{sessionId, workspaceName, workspacePath}`, so a window's real workspace name can be shown for its bridge session. |
-| `GET/POST /api/window/:sessionId/mute` | Mute every client belonging to one editor window. |
-| `GET /api/sessions`, `DELETE /api/sessions/:clientId` | Raw MCP session list / drop one. |
-| `GET /api/clients` | Connected clients with panel numbering, kinds (`mcp`/`sse`/`waiter`), workspace name and disabled flag. |
-| `POST /api/clients/:tag/rename`, `/api/clients/:id/disable` | Persisted display alias / per-client kill switch. |
-| `POST /api/clients/:tag/reconnect`, `/api/clients/:tag/panel/:sessionId/reconnect` | Drop every connection for a tag, or just one panel. |
-| `POST /api/test/{sound,tts,desktop,telegram,sms,email,ntfy,discord,slack,teams}` | One-shot test send per channel. |
-| `GET /api/voices` | English neural voices from msedge-tts, cached 24 h. |
-| `GET /api/telegram/chats`, `/api/slack/channels`, `/api/sms/numbers` | Pickers backing the UI. |
-| `GET /api/slack/status`, `/api/discord/status`, `/api/gcloud/status` | Connection state for the UI badges. |
-| `GET /auth/{google,slack,discord}/start`, `/callback`; `DELETE /auth/{google,slack,discord}` | OAuth connect / disconnect. |
-| `GET /api/google/open-apppasswords`, `POST /api/google/apppassword`, `GET /api/gcloud/login` | Gmail App Password helper flow and the gcloud sign-in it can fall back on. |
-| `POST /api/agent/notify`, `GET /api/agent/inbox/poll`, `GET /api/agent/inbox/wait`, `POST /api/agent/inbox/inject`, `POST /api/agent/slack/reply` | Plain-HTTP agent API — same behaviour as the MCP tools, no transport required. Gated by `x-notify-key` when `NOTIFY_AGENT_KEY` is set. |
-| `POST /api/session/state` | A session reports itself busy/idle so the bus can answer "Claude is busy, ~Ns". |
-| `POST /api/slack/events` | Slack Events API receiver; HMAC-verified when `SLACK_SIGNING_SECRET` is set. |
-| `POST /api/ui/visibility` | The web UI heartbeats its own visibility; while visible, non-`high` notifications stay desktop-only. |
-| `GET /reply/:token`, `POST /reply/:token` | One-shot web reply page for `ask` over email. |
-| `GET /v1/health`, `/v1/info` | Liveness (used by the VS Code extension) and version stub. |
-| `/:topic/sse`, `/:topic/json`, `PUT`/`POST /:topic`, `/:topic/subscribers` | Built-in ntfy protocol server (also mounted under `/ntfy/…`). |
-
-`POST /__test__/inject-inbox` and `GET /__test__/slack-clients` exist only when
-`NOTIFY_MCP_TEST_ENDPOINTS=1`.
-
-## Environment
-
-| Variable | Read by | Effect |
-|---|---|---|
-| `PORT` / `NOTIFY_MCP_PORT` | server / bridge | Listen port, default 3737. |
-| `ENABLE_MCP` | server | `1` enables `/mcp`. The bridge always sets it when it spawns the server; a manual relaunch that forgets it makes every MCP tool 404. |
-| `NOTIFY_MCP_CONFIG_DIR` | server | Config + inbox-drop root, default `~/.notify-mcp`. |
-| `NOTIFY_MCP_TAG` | bridge, `notify-watch.sh`, drain hook | Explicit session tag. |
-| `NOTIFY_AGENT_KEY` | server | When set, `/api/agent/*` requires header `x-notify-key`. |
-| `SLACK_BOT_TOKEN`, `SLACK_CHANNEL_ID`, `SLACK_POLL_INTERVAL`, `SLACK_SIGNING_SECRET` | server | Slack bus credentials, poll interval (seconds, default 2) and Events-API signature verification. |
-| `NOTIFY_MCP_NO_OPEN`, `BROWSER=none` | server | Suppress the first-run browser pop. |
-| `NOTIFY_MCP_TEST_ENDPOINTS` | server | `1` enables the test-only routes, isolates the inbox drop dir, and skips the live Telegram/Slack listeners. |
-| `CLAUDE_PROJECT_DIR`, `CLAUDE_CODE_SESSION_ID` | bridge, extension | Supplied by the host; drive tag derivation and subagent folding. |
-
-## Scripts
-
-| Script | What it does |
+| Face | Meaning |
 |---|---|
-| `notify-ui.sh` | Build if `dist/ui/server.js` is missing, then run the server in the foreground (**without** `ENABLE_MCP`). |
-| `restart.sh` | `npm run build:ui`, kill the running `dist/ui/server.js`, relaunch detached to `/tmp/notify-mcp.log`. |
-| `bus-up.sh` | Singleton watchdog: keeps `:3737` listening, redeploys when `dist/ui/server.js` changes on disk, and keeps one `notify-watch.sh` alive. Logs to `.run/`. |
-| `notify-watch.sh` | Detached responder. Long-polls `/api/agent/inbox/wait` for `<host>-<folder>-bot`, and passes every message **verbatim** to a headless `claude -p` that answers via `POST /api/agent/slack/reply`. |
-| `scripts/agent-notify.sh`, `agent-poll-inbox.sh`, `agent-wait-inbox.sh`, `agent-listen-loop.sh` | curl wrappers over the plain-HTTP agent API (`NOTIFY_BASE_URL`, `NOTIFY_AGENT_KEY`, `NOTIFY_TAG`, `NOTIFY_ON_MESSAGE_CMD`). |
-| `scripts/bus-startup-task.sh` | Registers `bus-up.sh` with Windows Task Scheduler. |
-| `scripts/run-tunnel-loop.sh` | Keeps a localtunnel pointed at the port. |
-| `release.sh`, `setup-secrets.sh` | npm + Marketplace publish, and the guided credential setup it calls on first run. |
+| $(bell) Notify | running and able to deliver |
+| $(bell-slash) Muted | master mute is on — everything, including `high`, is dropped |
+| $(bell-slash) Win Muted | this window is muted |
+| $(error) Notify DOWN | the server is not answering at all |
+| $(error) Notify UNCHECKED | the delivery check never got an answer — nothing is claimed either way |
+| $(error) Notify NO REPORT | the server answered but said nothing about delivery |
+| $(error) Notify MCP OFF | the MCP endpoint is disabled — nothing can be sent through it |
+| $(error) Notify NO CHANNEL | no channel is enabled, so every send reaches nobody |
+| $(bell) Notify N on | channels are enabled and NOTHING has measured whether any can carry |
+| $(error) Notify MUTE UNREAD | the mute state came back unreadable — not the same as "not muted" |
+
+## The reload control (VS Code extension)
+
+**🔃 Reload** joins the shared Restorable Reload used by every Bullseye extension. Notify
+brings back nothing across a reload — it keeps no per-window state: the notify process is
+the one started at login, outside every window, and every setting lives in the config
+file, which a reload does not touch. So it registers the lifecycle and no participants.
 
 ## Tests
 
-`tests/smoke.test.mjs` — end-to-end only. It spawns a real server on a random free
-port with an isolated config dir, drives it over real HTTP, and runs the stdio bridge
-as a real subprocess; a local capture server stands in for the Slack webhook. Run with
-`npm test` (which builds first) or `node --test tests/smoke.test.mjs` against an
+The suite is end-to-end: it spawns the real built server on a random config dir and
+drives it over a real MCP session, with local stand-in servers for the Telegram and
+Slack APIs. Run with `npm test` (which builds first) or `npm run test:files` against an
 existing `dist/`.
 
 ## License

package/assets/bn-logo.svg

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512" role="img" aria-label="BullseyeNotify">
+  <title>BullseyeNotify</title>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#1a3550"/>
+      <stop offset="55%" stop-color="#1f5a96"/>
+      <stop offset="100%" stop-color="#4ea3ff"/>
+    </linearGradient>
+    <radialGradient id="glow" cx="0.35" cy="0.3" r="0.7">
+      <stop offset="0%" stop-color="#ffffff" stop-opacity="0.22"/>
+      <stop offset="100%" stop-color="#ffffff" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+  <rect width="512" height="512" rx="112" fill="url(#bg)"/>
+  <rect width="512" height="512" rx="112" fill="url(#glow)"/>
+  <circle cx="256" cy="256" r="196" fill="#ffffff"/>
+  <circle cx="256" cy="256" r="196" fill="none" stroke="#1a3550" stroke-width="8"/>
+  <circle cx="256" cy="256" r="150" fill="#1f5a96"/>
+  <circle cx="256" cy="256" r="104" fill="#ffffff"/>
+  <circle cx="256" cy="256" r="58" fill="#34d399"/>
+  <circle cx="256" cy="256" r="22" fill="#0f2a40"/>
+  <path d="M256 256 L420 92" stroke="#ffffff" stroke-width="18" stroke-linecap="round"/>
+  <path d="M420 92 l-6 -50 m6 50 l50 -6" stroke="#ffffff" stroke-width="18" stroke-linecap="round" fill="none"/>
+</svg>