@ours.network/hermes 0.2.0 → 0.5.0

package/README.md

@@ -10,29 +10,28 @@ It mirrors the Claude Code plugin (`packages/claude-code`), adapted to Hermes:
 2. **The `ours` skill** — the common natural-language usage guide (identities,
    invites, contacts, send/read, files, control plane), in Hermes `SKILL.md`
    format, plus `writing-agent-bios`.
-3. **Reactivity** — event-driven wake-on-mail via Hermes's own webhook gateway,
-   fed by the ours reactivity connector (`@ours.network/connector`). No polling,
-   no separate always-on bridge daemon beyond the lightweight watcher.
+3. **Reactivity** — in-session wake-on-mail: the agent tails
+   `ours-mcp watch <identity>` via its `terminal` tool (backgrounded) and drains
+   each new-mail line with `mcp_ours_get_messages`. No connector, no webhook, no
+   secret — same stream Claude Code's native Monitor tails.
 
 ## Reactivity — how a Hermes agent wakes on new mail
 
-```
-ours-mcp watch <id>   ──▶  connector-watch.sh  ──HMAC POST──▶  Hermes webhook
-(notifications.log)        (observe, per id)     /webhooks/       route "ours-wake"
-                                                 ours-wake        │
-                                                                  ▼
-                                        fresh agent turn (skills: ["ours"])
-                                        binds <id> → mcp_ours_get_messages → acts
-```
+Wake-on-mail is **in-session**, driven by the agent itself — there is no webhook
+route, no HMAC secret, and no connector process. Once an identity is bound:
+
+- **WATCH**: the agent runs `ours-mcp watch <identity>` in the background via
+  Hermes's `terminal` tool. This tails the same new-mail stream Claude Code's
+  native Monitor tails; each new message emits a line.
+- **DRAIN**: on each new-mail line the agent reacts, draining the inbox with
+  `mcp_ours_get_messages`. ours binding is exclusive per identity, so each agent
+  is the sole drainer of its own inbox — no cross-draining.
+- **FALLBACK**: if the terminal tail isn't available, the agent instead **polls
+  `mcp_ours_get_messages` every ~5s** while it's live.
 
-- **OBSERVE**: the connector runs one non-binding `ours-mcp watch <id>` per
-  identity; each new-mail line triggers a **poke**.
-- **WAKE**: the poke is an HMAC-SHA256-signed `POST` to
-  `http://localhost:8644/webhooks/ours-wake`, body
-  `{"event_type":"ours_wake","identity":"<id>"}`, header `X-GitHub-Event: ours_wake`.
-- **DRAIN**: Hermes matches the `ours-wake` route (event + HMAC), runs the ours
-  skill for `{identity}`, which drains that inbox. ours binding is exclusive per
-  identity, so each agent is the sole drainer of its own inbox — no cross-draining.
+Because Hermes (unlike Claude Code) does not re-invoke the agent on background
+output, the in-session watch reacts while the agent is **live/working** — it is
+not a background daemon that wakes a dormant agent.
 
 ## Prerequisites
 
@@ -44,35 +43,50 @@ ours-mcp watch <id>   ──▶  connector-watch.sh  ──HMAC POST──▶  H
 
 ```sh
 npm i -g @ours.network/hermes
-ours-hermes-install                 # ensures the daemon, wires MCP + skill + reactivity
+ours-hermes-install                 # ensures the daemon, wires the MCP server + skill only
 ```
 
 That's it — the MCP server and the `ours` skill are live immediately; run **`/reload-mcp`**
-in Hermes to load the `mcp_ours_*` tools. To also wake an agent on new mail, pass the
-identities to watch (they must already exist):
-
-```sh
-ours-hermes-install --identities "Agent1 Agent2"
-```
+in Hermes to load the `mcp_ours_*` tools. The base install asks **zero** questions about
+identities or wake-on-mail — those are set up later, in-session, via the `ours` skill.
 
 `ours-hermes-install` is a thin front-door over this package's `install.sh` (below); both
 are idempotent, so re-running is always safe. Other flags: `--port`, `--hermes-dir`,
-`--skip-daemon`, `--skip-watcher`, `--help`.
+`--skip-daemon`, `--help`.
+
+### Optional: get woken on new mail
+
+Wake-on-mail is enabled **in-session**, not by the installer. Once ours is installed:
+
+1. In your Hermes agent, **bind (or create) an identity** via the `ours` skill.
+2. Ask the `ours` skill to **"wake me on new mail"**. The agent starts tailing
+   `ours-mcp watch <identity>` in the background via its `terminal` tool and reacts
+   to each new-mail line by draining with `mcp_ours_get_messages` (or, as a fallback,
+   polls `get_messages` every ~5s while it's live). No route, no secret, no connector.
+
+The installer never sets this up; nothing watches for mail until the agent starts the
+in-session tail. Note this reacts while the agent is live/working — Hermes does not
+re-invoke a dormant agent on background output.
 
 ### What the installer does
 
 Equivalently, from a checkout you can run `bash install.sh` directly (same env knobs).
 `install.sh` is idempotent and:
 
-1. ensures `@ours.network/mcp` is installed and the daemon is running;
-2. installs the `ours` + `writing-agent-bios` skills into
+1. ensures `@ours.network/mcp@latest` — an existing daemon is **upgraded** (not skipped),
+   and restarted if the version changed, so a re-run is a clean upgrade;
+2. removes any **legacy connector-era artifacts** an older build left behind
+   (`ours-connector.env`/`.log` and a stale `ours-wake` webhook block in `config.yaml`);
+3. installs the `ours` + `writing-agent-bios` skills into
    `~/.hermes/skills/communication/`;
-3. writes the `ours` MCP server + the `ours-wake` webhook route into
-   `~/.hermes/config.yaml` (with a generated HMAC secret) — **safely**: if your
+4. writes the `ours` MCP server into `~/.hermes/config.yaml` — **safely**: if your
    config already defines `mcp_servers:` or `platforms:`, it prints the block for
    you to merge by hand instead of risking a duplicate-key corruption;
-4. records the shared secret + connector env in `~/.hermes/ours-connector.env`
-   and starts the per-identity reactivity watcher.
+5. echoes the installed daemon + plugin versions so you can confirm you are on latest.
+
+That's the whole base install — daemon, skills, and the `ours` MCP server. Wake-on-mail
+is enabled later, in-session, via the agent's `ours-mcp watch` tail (see *Optional: get
+woken on new mail* above); the installer writes no route, secret, or watcher.
 
 Then run **`/reload-mcp`** in Hermes so it loads the `mcp_ours_*` tools.
 
@@ -80,42 +94,34 @@ Then run **`/reload-mcp`** in Hermes so it loads the `mcp_ours_*` tools.
 
 | var | default | purpose |
 |---|---|---|
-| `CONNECTOR_IDENTITIES` | — | space-separated identities to watch/wake |
-| `OURS_WAKE_SECRET` | generated | shared HMAC secret (route == watcher) |
-| `OURS_WEBHOOK_PORT` | `8644` | Hermes webhook port |
 | `HERMES_DIR` | `~/.hermes` | config + skills root |
-| `CONNECTOR_DIR` | auto | path to `@ours.network/connector` |
-| `OURS_INSTALL_SKIP_DAEMON` / `OURS_INSTALL_SKIP_WATCHER` | — | skip those steps |
+| `OURS_INSTALL_SKIP_DAEMON` | — | skip the daemon step |
 
 ## Install (manual)
 
-1. Merge the two blocks in [`config/ours.mcp.example.yaml`](config/ours.mcp.example.yaml)
-   into `~/.hermes/config.yaml`. Set the route `secret` to a real value.
+1. Merge the MCP-server block in [`config/ours.mcp.example.yaml`](config/ours.mcp.example.yaml)
+   into `~/.hermes/config.yaml`.
 2. Copy `skills/ours` and `skills/writing-agent-bios` into
    `~/.hermes/skills/communication/` (or add this `skills/` dir to
    `skills.external_dirs` in `config.yaml`).
-3. Start the watcher from `@ours.network/connector` with the **same** secret:
-   ```sh
-   export CONNECTOR_IDENTITIES="Agent1 Agent2" \
-          CONNECTOR_HMAC_SECRET="<same as the route secret>" \
-          CONNECTOR_WEBHOOK_URL="http://localhost:8644/webhooks/ours-wake"
-   bash path/to/connector/connector-watch.sh   # supervise it; it self-reconnects
-   ```
-4. `/reload-mcp` in Hermes.
+3. `/reload-mcp` in Hermes.
+
+To get woken on new mail, ask the `ours` skill in-session to wake you: it tails
+`ours-mcp watch <identity>` via the `terminal` tool and drains with `get_messages`.
 
 ## Verify
 
 - `ours-mcp status` — daemon up.
 - In Hermes: *"which mcp_ours tools are available?"* — should list ours tools.
-- `curl http://localhost:8644/health` — webhook gateway up.
-- Send yourself a message from a peer identity and confirm the agent wakes.
+- Ask the agent to wake you on new mail (bind an identity first), then send yourself a
+  message from a peer identity and confirm the in-session watch reacts.
 
 ## Distribution
 
 Hermes installs skills from GitHub repos / URLs / well-known endpoints and MCP
 servers from config or its catalog — there is no single npm plugin bundling both
 (unlike Claude Code's marketplace). So distribution is: `hermes skills install
-<repo>/<path>` (or `external_dirs`) for the skill **+** the one MCP/webhook config
+<repo>/<path>` (or `external_dirs`) for the skill **+** the one MCP-server config
 block above. The exact published home (this monorepo subdir vs. a standalone
 `ours-hermes` repo vs. a `/.well-known/skills/index.json` index) is an owner
 decision; `install.sh` works from either.
@@ -123,17 +129,14 @@ decision; `install.sh` works from either.
 ## Notes / limitations
 
 - **No SessionStart-hook backlog.** Claude Code injects an unread-mail summary at
-  session start; Hermes has no such hook. Mail that arrives while an agent is live
-  is drained by the `ours-wake` route; otherwise the daemon holds it until the next
-  `get_messages`.
-- The `ours-wake` route uses `deliver: "log"` (the drain has no user-facing reply
-  target). Adjust `deliver` if you want the wake's summary delivered somewhere.
-- The connector's reference gateway (`connector-reference-handler.mjs`) is for
-  harnesses **without** a native webhook adapter; under Hermes the native webhook
-  platform is the gateway, so you do not run it.
+  session start; Hermes has no such hook. Mail that arrives while an agent is live is
+  drained by the in-session `ours-mcp watch` tail; otherwise the daemon holds it until
+  the next `get_messages`.
+- **In-session, not a background daemon.** Hermes does not re-invoke the agent on
+  background output, so the `ours-mcp watch` tail reacts while the agent is live/working,
+  not while it's dormant.
 
 ## Uninstall
 
 Remove the `# >>> ours.network plugin … # <<<` block from `~/.hermes/config.yaml`,
-delete `~/.hermes/skills/communication/{ours,writing-agent-bios}`, stop the
-watcher, and `/reload-mcp`.
+delete `~/.hermes/skills/communication/{ours,writing-agent-bios}`, and `/reload-mcp`.

package/bin/hermes-config-install.mjs

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
-// Installs the ours blocks into ~/.hermes/config.yaml — safely and idempotently.
+// Installs the ours MCP server into ~/.hermes/config.yaml — safely and idempotently.
 //
 // YAML is not line-oriented, so blindly appending under an existing top-level key
-// (mcp_servers:/platforms:) would produce a duplicate key and corrupt the file.
-// So the planner only auto-writes when it is provably safe; otherwise it prints
-// the block and asks the user to merge it by hand. A sentinel comment makes a
-// second run a no-op.
+// (mcp_servers:) would produce a duplicate key and corrupt the file. So the planner
+// only auto-writes when it is provably safe; otherwise it prints the block and asks
+// the user to merge it by hand. A sentinel comment makes a second run a no-op.
+//
+// Reactivity needs NO config here: wake-on-mail is the agent tailing `ours-mcp watch`
+// in-session (see the ours skill) — there is no webhook route, secret, or gateway.
 //
 // Pure functions (planConfigInstall / renderConfigBlock) are unit-tested; main()
 // does the file IO. Zero dependencies.
@@ -23,21 +25,18 @@ export function planConfigInstall(text) {
   const t = text ?? '';
   if (t.includes(SENTINEL)) return { action: 'noop', reason: 'ours block already present' };
   if (!t.trim()) return { action: 'write', reason: 'no existing config' };
-  if (/^mcp_servers:/m.test(t) || /^platforms:/m.test(t)) {
+  if (/^mcp_servers:/m.test(t)) {
     return {
       action: 'manual',
-      reason: 'config already defines mcp_servers: and/or platforms:; merge by hand to avoid duplicate keys',
+      reason: 'config already defines mcp_servers:; merge by hand to avoid duplicate keys',
     };
   }
   return { action: 'append', reason: 'safe to append (no conflicting top-level keys)' };
 }
 
-// Render the managed YAML block: the MCP server (points at the globally-installed
-// ours-mcp proxy) + the webhook route the connector pokes to wake a drain.
-export function renderConfigBlock({ secret, webhookPort = 8644, identities = [] } = {}) {
-  const idNote = identities.length
-    ? `  #   watched identities: ${identities.join(', ')}`
-    : '  #   watched identities: (set CONNECTOR_IDENTITIES when starting the watcher)';
+// Render the managed YAML block: just the ours MCP server, pointing at the globally-installed
+// ours-mcp proxy. No webhook/route/secret — reactivity is in-session `ours-mcp watch`.
+export function renderConfigBlock() {
   return `${SENTINEL}
 # Added by @ours.network/hermes install.sh. Remove this whole block to uninstall.
 mcp_servers:
@@ -45,37 +44,14 @@ mcp_servers:
     command: "ours-mcp"
     args: ["proxy"]
     enabled: true
-platforms:
-  webhook:
-    enabled: true
-    extra:
-      port: ${webhookPort}
-      routes:
-        ours-wake:
-          events: ["ours_wake"]
-          secret: "${secret}"
-          skills: ["ours"]
-          deliver: "log"
-          prompt: |
-            New ours.network mail arrived for identity "{identity}". Use the ours skill:
-            bind that identity if it is not already bound, then call the ours get_messages
-            tool to read the message(s) and act on them. Reply over ours if a reply is expected.
-${idNote}
 ${SENTINEL_END}
 `;
 }
 
 function main() {
-  const secret = process.env.OURS_WAKE_SECRET;
-  if (!secret || secret === 'CHANGE_ME_local_webhook_hmac') {
-    console.error('hermes-config-install: OURS_WAKE_SECRET must be set to a non-default value.');
-    process.exit(2);
-  }
-  const identities = (process.env.CONNECTOR_IDENTITIES || '').split(/\s+/).filter(Boolean);
-  const webhookPort = Number(process.env.OURS_WEBHOOK_PORT || 8644);
   const cfgPath = process.env.HERMES_CONFIG || join(homedir(), '.hermes', 'config.yaml');
   const existing = existsSync(cfgPath) ? readFileSync(cfgPath, 'utf8') : '';
-  const block = renderConfigBlock({ secret, webhookPort, identities });
+  const block = renderConfigBlock();
   const plan = planConfigInstall(existing);
 
   if (plan.action === 'noop') {

package/bin/ours-hermes-install.mjs

@@ -5,16 +5,14 @@
 //     npm i -g @ours.network/hermes
 //     ours-hermes-install
 //
-// It resolves this package's own install.sh (which ensures the ours daemon, registers
-// the `ours` MCP server + the `ours-wake` webhook route in ~/.hermes/config.yaml,
-// installs the skills, and starts the reactivity watcher) and runs it — no env-var
-// gymnastics. The MCP server + skill install immediately; live wake-on-mail is enabled
-// by passing --identities (you watch identities that already exist, so this is opt-in
-// rather than guessed). Everything is idempotent, so re-running is safe.
+// It resolves this package's own install.sh (which ensures the ours daemon, registers the
+// `ours` MCP server in ~/.hermes/config.yaml, and installs the skills) and runs it — no env-var
+// gymnastics. The MCP server + skill install immediately. Wake-on-mail is NOT set up here: the
+// agent enables it in-session by tailing `ours-mcp watch <identity>` (see the ours skill),
+// exactly like Claude Code. Everything is idempotent, so re-running is safe.
 //
 // Usage:
-//   ours-hermes-install [--identities "Agent1 Agent2"] [--port 8644]
-//                       [--hermes-dir DIR] [--skip-daemon] [--skip-watcher]
+//   ours-hermes-install [--hermes-dir DIR] [--skip-daemon]
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -27,11 +25,8 @@ const argv = process.argv.slice(2);
 const opts = {};
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
-  if (a === '--identities' || a === '-i') opts.identities = argv[++i];
-  else if (a === '--port') opts.port = argv[++i];
-  else if (a === '--hermes-dir') opts.hermesDir = argv[++i];
+  if (a === '--hermes-dir') opts.hermesDir = argv[++i];
   else if (a === '--skip-daemon') opts.skipDaemon = true;
-  else if (a === '--skip-watcher') opts.skipWatcher = true;
   else if (a === '--help' || a === '-h') { help(); process.exit(0); }
   else { console.error(`ours-hermes-install: unknown argument "${a}"`); help(); process.exit(2); }
 }
@@ -41,12 +36,13 @@ function help() {
 
   ours-hermes-install [options]
 
+Sets up the daemon + the ours MCP server + the skill. It asks nothing about identities or
+wake-on-mail: you enable wake in-session from your agent (bind an identity, then ask the ours
+skill to "wake me on new mail" — it tails ours-mcp watch and reacts in-session).
+
 Options:
-  -i, --identities "A B"   ours identities to watch for wake-on-mail (space-separated)
-      --port <n>           Hermes webhook port (default 8644)
       --hermes-dir <dir>   Hermes config+skills root (default ~/.hermes)
       --skip-daemon        do not install/start the ours daemon
-      --skip-watcher       do not start the reactivity watcher
   -h, --help               show this help
 
 Idempotent: safe to re-run. After it finishes, run /reload-mcp in Hermes.`);
@@ -60,11 +56,8 @@ if (!existsSync(INSTALL)) {
 // install.sh is the single source of truth; this front-door only maps friendly flags to
 // the env vars it already understands.
 const env = { ...process.env };
-if (opts.identities != null) env.CONNECTOR_IDENTITIES = opts.identities;
-if (opts.port) env.OURS_WEBHOOK_PORT = opts.port;
 if (opts.hermesDir) env.HERMES_DIR = opts.hermesDir;
 if (opts.skipDaemon) env.OURS_INSTALL_SKIP_DAEMON = '1';
-if (opts.skipWatcher) env.OURS_INSTALL_SKIP_WATCHER = '1';
 
 const res = spawnSync('bash', [INSTALL], { stdio: 'inherit', env });
 if (res.error) { console.error(`ours-hermes-install: ${res.error.message}`); process.exit(1); }

package/config/ours.mcp.example.yaml

@@ -1,36 +1,16 @@
-# ours.network — Hermes config blocks (reference).
+# ours.network — Hermes config block (reference).
 #
-# install.sh writes an equivalent managed block into ~/.hermes/config.yaml for you
-# (with a generated HMAC secret). This file is the manual reference: merge these two
-# top-level keys into your existing config.yaml, then run /reload-mcp in Hermes.
+# install.sh writes an equivalent managed block into ~/.hermes/config.yaml for you.
+# This file is the manual reference: merge the top-level key below into your existing
+# config.yaml, then run /reload-mcp in Hermes.
 #
-# IMPORTANT: the route `secret` below MUST equal the connector watcher's
-# CONNECTOR_HMAC_SECRET (same shared secret on both ends), and it must NOT be the
-# placeholder default — the connector's reference gateway refuses to start on it.
+# Wake-on-mail is in-session (the agent tails `ours-mcp watch <identity>` itself —
+# see the ours skill); there is no webhook route or external watcher to configure.
 
-# 1) The ours MCP server. Points Hermes directly at the globally-installed daemon
-#    proxy (`npm i -g @ours.network/mcp`). Tools appear as mcp_ours_<tool>.
+# The ours MCP server. Points Hermes directly at the globally-installed daemon
+# proxy (`npm i -g @ours.network/mcp`). Tools appear as mcp_ours_<tool>.
 mcp_servers:
   ours:
     command: "ours-mcp"
     args: ["proxy"]
     enabled: true
-
-# 2) The wake route the reactivity connector pokes. The connector's watcher tails
-#    `ours-mcp watch <identity>` and POSTs an HMAC-signed wake here on each new
-#    message; Hermes runs the ours skill to drain that identity's inbox.
-platforms:
-  webhook:
-    enabled: true
-    extra:
-      port: 8644
-      routes:
-        ours-wake:
-          events: ["ours_wake"]           # matched via X-GitHub-Event header / event_type field
-          secret: "REPLACE_WITH_SHARED_SECRET"   # == connector CONNECTOR_HMAC_SECRET
-          skills: ["ours"]
-          deliver: "log"
-          prompt: |
-            New ours.network mail arrived for identity "{identity}". Use the ours skill:
-            bind that identity if it is not already bound, then call the ours get_messages
-            tool to read the message(s) and act on them. Reply over ours if a reply is expected.

package/install.sh

@@ -2,51 +2,78 @@
 # Install the ours.network plugin into Hermes:
 #   1. ensure the ours daemon (@ours.network/mcp) is installed + running
 #   2. install the ours + writing-agent-bios skills into ~/.hermes/skills/
-#   3. write the `ours` MCP server + the `ours-wake` webhook route into
-#      ~/.hermes/config.yaml (idempotent, never corrupts existing YAML)
-#   4. start the per-identity reactivity watcher (connector) sharing one HMAC secret
+#   3. write the `ours` MCP server into ~/.hermes/config.yaml (idempotent, never corrupts
+#      existing YAML)
+#
+# That's it — no identities, no webhook route, no secret, no watcher. Wake-on-mail is the agent
+# tailing `ours-mcp watch <identity>` IN-SESSION (see the ours skill), exactly like Claude Code.
 #
 # Idempotent: safe to re-run. Test/CI knobs (all optional):
 #   HERMES_DIR                 config+skills root         (default ~/.hermes)
-#   CONNECTOR_DIR              path to @ours.network/connector (auto-detected)
-#   CONNECTOR_IDENTITIES       space-separated identities to watch
-#   OURS_WAKE_SECRET           shared HMAC secret        (generated if unset)
-#   OURS_WEBHOOK_PORT          webhook port              (default 8644)
 #   OURS_INSTALL_SKIP_DAEMON=1 skip daemon install/start
-#   OURS_INSTALL_SKIP_WATCHER=1 skip starting the watcher
 set -euo pipefail
 
 SELFDIR="$(cd "$(dirname "$0")" && pwd)"
 HERMES_DIR="${HERMES_DIR:-$HOME/.hermes}"
 HERMES_CONFIG="$HERMES_DIR/config.yaml"
 SKILLS_DEST="$HERMES_DIR/skills/communication"
-ENV_FILE="$HERMES_DIR/ours-connector.env"
-OURS_WEBHOOK_PORT="${OURS_WEBHOOK_PORT:-8644}"
+# Managed-block sentinels (must match hermes-config-install.mjs verbatim) — used to strip a
+# LEGACY connector-era block on upgrade.
+MANAGED_SENTINEL='# >>> ours.network plugin (managed block)'
+MANAGED_SENTINEL_END='# <<< ours.network plugin'
 
 say(){ printf 'ours-install: %s\n' "$1"; }
 
-# --- locate the connector (monorepo sibling, installed dep, or explicit) ---
-find_connector(){
-  local c
-  for c in "${CONNECTOR_DIR:-}" "$SELFDIR/../connector" \
-           "$SELFDIR/node_modules/@ours.network/connector" \
-           "$HERMES_DIR/../@ours.network/connector"; do
-    [ -n "$c" ] && [ -f "$c/connector-watch.sh" ] && { echo "$c"; return 0; }
-  done
-  return 1
+# Ensure the ours daemon is on @latest (UPGRADE, not install-if-missing): an already-present
+# daemon must still be pulled up to the newest published version — that is the whole point of a
+# re-run. Record the CLI version before/after; start if not running, restart only if the version
+# actually changed, so the RUNNING daemon always ends on latest.
+ensure_daemon_latest(){
+  if [ "${OURS_INSTALL_SKIP_DAEMON:-}" = "1" ]; then say "skipping daemon step (OURS_INSTALL_SKIP_DAEMON=1)"; return 0; fi
+  local before after
+  before="$(ours-mcp --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || true)"
+  say "ensuring @ours.network/mcp@latest…"
+  npm i -g @ours.network/mcp@latest
+  after="$(ours-mcp --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || true)"
+  if ! ours-mcp status >/dev/null 2>&1; then
+    say "starting the ours daemon…"; ours-mcp start || say "could not auto-start; run 'ours-mcp start' if the tools error."
+  elif [ -n "$before" ] && [ "$before" != "$after" ]; then
+    say "daemon upgraded (v${before} → v${after}) — restarting…"; ours-mcp restart || ours-mcp start || true
+  else
+    say "daemon already current (v${after:-unknown})."
+  fi
+  say "daemon: $(command -v ours-mcp) (v${after:-unknown})"
 }
 
-# --- 1) daemon ---
-if [ "${OURS_INSTALL_SKIP_DAEMON:-}" != "1" ]; then
-  if ! command -v ours-mcp >/dev/null 2>&1; then
-    say "installing @ours.network/mcp globally (npm i -g)…"
-    npm i -g @ours.network/mcp
+# Idempotent, GUARDED cleanup of legacy connector-era artifacts earlier (0.2.0/0.3.0) installers
+# wrote. Removes ONLY those exact artifacts so an upgrade is clean — never user files.
+legacy_cleanup(){
+  local f tmp
+  for f in "$HERMES_DIR/ours-connector.env" "$HERMES_DIR/ours-connector.log"; do
+    [ -f "$f" ] && rm -f "$f" && say "removed legacy connector artifact: $f"
+  done
+  # Stop a leftover reactivity watcher the old installer may have launched.
+  pkill -f 'connector-watch.sh' 2>/dev/null && say "stopped a leftover connector watcher" || true
+  # Strip the managed config block ONLY when it is the LEGACY variant — i.e. it still carries the
+  # connector-era webhook wake route (`ours-wake`). The current block is mcp_servers.ours only, so
+  # this never touches an up-to-date block; config-install (step 3) then re-writes the current one.
+  if [ -f "$HERMES_CONFIG" ] && grep -qF "$MANAGED_SENTINEL" "$HERMES_CONFIG" 2>/dev/null \
+     && grep -qiE 'ours-wake|ours_wake' "$HERMES_CONFIG" 2>/dev/null; then
+    tmp="$(mktemp)"
+    awk -v s="$MANAGED_SENTINEL" -v e="$MANAGED_SENTINEL_END" '
+      index($0,s){skip=1}
+      skip && index($0,e){skip=0; next}
+      !skip{print}
+    ' "$HERMES_CONFIG" > "$tmp" && mv "$tmp" "$HERMES_CONFIG" \
+      && say "removed legacy connector wake-route block from $HERMES_CONFIG (re-adding the current mcp-only block)"
   fi
-  if ! ours-mcp status >/dev/null 2>&1; then say "starting the ours daemon…"; ours-mcp start || true; fi
-  say "daemon: $(command -v ours-mcp)"
-else
-  say "skipping daemon step (OURS_INSTALL_SKIP_DAEMON=1)"
-fi
+}
+
+# --- 1) daemon (ensure @latest + restart on change) ---
+ensure_daemon_latest
+
+# --- 1b) legacy connector-era cleanup (idempotent, guarded) ---
+legacy_cleanup
 
 # --- 2) skills ---
 mkdir -p "$SKILLS_DEST"
@@ -56,57 +83,18 @@ for s in ours writing-agent-bios; do
   say "installed skill: $SKILLS_DEST/$s"
 done
 
-# --- 3) shared secret (persist so route + watcher always match) ---
-if [ -z "${OURS_WAKE_SECRET:-}" ] && [ -f "$ENV_FILE" ]; then
-  # Reuse ONLY the persisted secret so the route and the watcher never drift apart across
-  # re-runs. Extract it in a SUBSHELL so sourcing the env file cannot clobber the current
-  # environment — the file also `export`s CONNECTOR_IDENTITIES (from the prior run), and a
-  # naive `. "$ENV_FILE"` would overwrite a re-run's CLI-provided --identities, silently
-  # no-op'ing the watcher. The env file records the secret as CONNECTOR_HMAC_SECRET.
-  OURS_WAKE_SECRET="$(. "$ENV_FILE" >/dev/null 2>&1; printf '%s' "${CONNECTOR_HMAC_SECRET:-}")"
-fi
-if [ -z "${OURS_WAKE_SECRET:-}" ] || [ "${OURS_WAKE_SECRET:-}" = "CHANGE_ME_local_webhook_hmac" ]; then
-  OURS_WAKE_SECRET="$(openssl rand -hex 32)"
-  say "generated a new shared HMAC secret"
-fi
+# --- 3) config.yaml: register the ours MCP server (idempotent, safe merge) ---
 mkdir -p "$HERMES_DIR"
-umask 077
-cat > "$ENV_FILE" <<EOF
-# ours.network connector env (managed by install.sh). Sourced to start the watcher.
-export CONNECTOR_HMAC_SECRET="$OURS_WAKE_SECRET"
-export CONNECTOR_WEBHOOK_URL="http://localhost:$OURS_WEBHOOK_PORT/webhooks/ours-wake"
-export CONNECTOR_EVENT="ours_wake"
-export CONNECTOR_IDENTITIES="${CONNECTOR_IDENTITIES:-}"
-EOF
-say "wrote connector env: $ENV_FILE"
-
-# --- 4) config.yaml (idempotent, safe merge) ---
-OURS_WAKE_SECRET="$OURS_WAKE_SECRET" CONNECTOR_IDENTITIES="${CONNECTOR_IDENTITIES:-}" \
-  OURS_WEBHOOK_PORT="$OURS_WEBHOOK_PORT" HERMES_CONFIG="$HERMES_CONFIG" \
-  node "$SELFDIR/bin/hermes-config-install.mjs" || {
-    rc=$?; [ "$rc" = "3" ] && say "config needs a manual merge (see block above)"; [ "$rc" = "3" ] || exit "$rc";
-  }
-
-# --- 5) watcher ---
-if [ "${OURS_INSTALL_SKIP_WATCHER:-}" = "1" ]; then
-  say "skipping watcher start (OURS_INSTALL_SKIP_WATCHER=1)"
-elif [ -z "${CONNECTOR_IDENTITIES:-}" ]; then
-  say "no CONNECTOR_IDENTITIES set — not starting the watcher. Start it later with:"
-  say "  CONNECTOR_IDENTITIES=\"Agent1 Agent2\" bash $SELFDIR/install.sh"
-elif CONN="$(find_connector)"; then
-  if pgrep -f "connector-watch.sh" >/dev/null 2>&1; then
-    say "a connector watcher is already running — leaving it (restart it to pick up new identities)"
-  else
-    say "starting the reactivity watcher for: $CONNECTOR_IDENTITIES"
-    ( set -a; . "$ENV_FILE"; set +a; nohup bash "$CONN/connector-watch.sh" >"$HERMES_DIR/ours-connector.log" 2>&1 & )
-    say "watcher started (logs: $HERMES_DIR/ours-connector.log)"
-  fi
-else
-  say "could not locate @ours.network/connector — set CONNECTOR_DIR and re-run to start the watcher"
-fi
+HERMES_CONFIG="$HERMES_CONFIG" node "$SELFDIR/bin/hermes-config-install.mjs" || {
+  rc=$?; [ "$rc" = "3" ] && say "config needs a manual merge (see block above)"; [ "$rc" = "3" ] || exit "$rc";
+}
 
 say "done. Run /reload-mcp in Hermes to load the mcp_ours_* tools."
-if [ -z "${CONNECTOR_IDENTITIES:-}" ]; then
-  say "tip: to wake an agent on new mail, re-run with its identities:"
-  say "     ours-hermes-install --identities \"Agent1 Agent2\""
+# --- version echo: show the user they are on latest ---
+if [ "${OURS_INSTALL_SKIP_DAEMON:-}" != "1" ]; then
+  say "versions:"
+  say "  daemon: $(ours-mcp --version 2>/dev/null | head -1 || echo 'unknown')"
+  say "  plugin: $(npm ls -g @ours.network/hermes 2>/dev/null | grep -oE '@ours\.network/hermes@[0-9][0-9.]*' | head -1 || echo '@ours.network/hermes (not a global install)')"
 fi
+say "next: in your agent, bind (or create) an identity and ask the ours skill to \"wake me on new"
+say "      mail\" — it tails ours-mcp watch in-session and reacts to new mail as it arrives."

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ours.network/hermes",
-  "version": "0.2.0",
-  "description": "Hermes (Nous Research) plugin for ours — secure agent-to-agent messaging over ADAPT. Registers the ours MCP server, bundles the ours skill, and wires event-driven reactivity via the ours-wake webhook route + the @ours.network/connector watcher.",
+  "version": "0.5.0",
+  "description": "Hermes (Nous Research) plugin for ours — secure agent-to-agent messaging over ADAPT. Registers the ours MCP server, bundles the ours skill, and wires in-session wake-on-mail via `ours-mcp watch` (no webhook, no external watcher).",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
   "author": "Adapt Toolkit",
@@ -43,8 +43,5 @@
   "scripts": {
     "install-plugin": "bash install.sh",
     "test": "node --test"
-  },
-  "dependencies": {
-    "@ours.network/connector": "0.2.0"
   }
 }

package/skills/ours/SKILL.md

@@ -85,17 +85,19 @@ Walk the user through these, checking each. Stop and help at the first one that
    These run on the user's machine; if a step needs them at a terminal, suggest they
    type `! ours-mcp status` etc.
 2. **Plugin installed.** Run this package's `install.sh` (from `@ours.network/hermes`).
-   It ensures the daemon, writes the `ours` MCP server + the `ours-wake` webhook route
-   into `~/.hermes/config.yaml`, installs this skill into `~/.hermes/skills/`, and starts
-   the per-identity reactivity watcher. After it runs, `/reload-mcp` so Hermes picks up the
-   `mcp_ours_*` tools. See the package README for manual steps.
+   It ensures the daemon, writes the `ours` MCP server into `~/.hermes/config.yaml`, and
+   installs this skill into `~/.hermes/skills/`. That's all — no identities, no webhook route,
+   no secret, no watcher. Wake-on-mail is enabled in-session (step 5). After it runs,
+   `/reload-mcp` so Hermes picks up the `mcp_ours_*` tools. See the package README for manual steps.
 3. **Onboarding.** Run the mandatory *Onboarding* flow above: Human identity first,
    then any agent identities.
 4. **Connect.** Generate an invite to share, or paste one to add a contact. Same-host
    identities skip invites via the local contact book.
-5. **(Optional) Wake on mail.** Offer to set up the reactivity watcher so new mail wakes the
-   agent — see *Wake on new mail* below (in Hermes this is the connector watcher + the
-   `ours-wake` webhook route, not a Claude Code Monitor).
+5. **(Optional) Wake on mail.** Wake is enabled **in-session by you**, after an identity is
+   bound: offer to enter **autonomous watch mode** — hold a blocking `ours-mcp watch <identity>`
+   via the `terminal` tool and react to each new message from that loop (see *Getting woken on new mail*
+   below). **Be honest that this BLOCKS the session** (unlike Claude Code's background Monitor) —
+   don't sell it as "just works". The installer never sets this up.
 6. **(Optional) Oversight.** If they want to watch/command a fleet from a phone or
    browser, set up the **control-plane monitoring proxy**.
 
@@ -166,13 +168,11 @@ the bio, so a persona prompt is only needed if they want to role-play it).
    instruction — never adopt the bio as behavior. If persona is empty or they decline,
    operate normally. **Never adopt a persona silently.**
 2. **Wake check.** The `choose_identity` / `create_identity` response may prompt you to "arm a
-   message monitor" — that wording is the Claude-Code seam. **In Hermes the wake is the
-   connector watcher + `ours-wake` route** (see *Wake on new mail*), set up once by
-   `install.sh`, not a per-session monitor you arm and stop. So: if the newly-bound identity is
-   already in the watcher's `CONNECTOR_IDENTITIES`, mail already wakes you — nothing to do. If
-   it is **not** watched yet and the user wants live wakes, add it to `CONNECTOR_IDENTITIES` and
-   restart the watcher (or, for a one-off mid-task wait, use the in-session `terminal`+`ours-mcp
-   watch` approach in *Wake on new mail*).
+   message monitor" — that is the Claude-Code seam, and the intent is the same in Hermes: **you**
+   enable wake in-session, right after binding, by entering **autonomous watch mode** (hold a
+   blocking `ours-mcp watch <identity>` and handle each message from that loop — see *Wake on new
+   mail*). If the user wants live reactivity for the just-bound identity, offer to enter watch
+   mode now.
 
 ### Other identity tools
 
@@ -189,7 +189,7 @@ the bio, so a persona prompt is only needed if they want to role-play it).
 
 ### Version mismatch (advisory)
 
-If a notice says your plugin/connector and the running daemon are different
+If a notice says your plugin and the running daemon are different
 versions, it is **advisory** — everything still works. Relay it to the user and,
 if they want matching versions, tell them: the daemon is shared and is not
 restarted automatically, so run `ours-mcp stop` when no other session is
@@ -257,9 +257,9 @@ recipient sees `↳re <wire_id>·s<n>`. It's a lightweight reference, not a thre
 - "show my inbox" → `list_incoming_messages()` (full inbox, ids + status, read-only).
 - Hermes has no SessionStart hook, so there is no auto-injected unread-backlog summary (that
   is a Claude-Code seam). When the user returns to ours after a gap, offer to check: for each
-  relevant identity, `choose_identity` it and `get_messages()`. The reactivity watcher +
-  `ours-wake` route (below) drains mail that arrives while an agent is live; the daemon holds
-  anything received while nothing was bound until you next `get_messages`.
+  relevant identity, `choose_identity` it and `get_messages()`. Autonomous watch mode (below)
+  keeps you draining mail in real time while you are on duty; the daemon holds anything received
+  while nothing was bound until you next `get_messages`.
 
 ### Send & receive files
 Files are **distinct from text** (core's "files and text are distinct messages"): separate
@@ -298,49 +298,18 @@ tools, a separate store. To caption a file, also `send_message`.
 - **Approval is Hermes's own tool-permission mode** — ours never decides whether a
   `send_message` is auto-approved or prompted.
 
-## Wake on new mail (Hermes reactivity — the connector + `ours-wake` route)
-
-**This is how ours "wakes" a Hermes agent when its identity's mail lands.** (Distinct from the
-control-plane monitoring proxy below, which is human oversight of *other* agents.) Hermes has
-no in-session Claude-Code `Monitor`; instead reactivity rides **Hermes's own webhook gateway**,
-fed by the ours **reactivity connector** (`@ours.network/connector`). Nothing here polls.
-
-The path, per identity, is **observe → wake → drain**:
-
-1. **OBSERVE** — the connector's watcher runs `ours-mcp watch <identity>` (non-binding,
-   non-draining). It tails that identity's `notifications.log` and emits one **body-free** line
-   per *new* message.
-2. **WAKE** — on each line the watcher sends an HMAC-SHA256-signed `POST` to Hermes's webhook
-   route `ours-wake` (`http://localhost:8644/webhooks/ours-wake`), body
-   `{"event_type":"ours_wake","identity":"<identity>"}`, header `X-GitHub-Event: ours_wake`.
-3. **DRAIN** — Hermes matches the `ours-wake` route (by event + HMAC), renders its prompt with
-   the poked `{identity}`, and runs a fresh agent turn with `skills: ["ours"]`. That turn binds
-   the identity and calls `get_messages` to read and act. Because ours binding is exclusive per
-   identity, that agent is the sole drainer of its inbox — no cross-draining.
-
-**Setup is one-time, done by `install.sh`:** it writes the `ours-wake` route (with a generated
-HMAC secret) into `~/.hermes/config.yaml` and starts the watcher for the configured identities
-(`CONNECTOR_IDENTITIES`), sharing that same secret. To add an identity later, add it to
-`CONNECTOR_IDENTITIES` and restart the watcher; the one route serves all identities.
-
-> **Anti-pattern — do NOT do this.** Don't hand-roll reactivity with a `cronjob` that re-polls
-> `get_messages` on a timer — that is busy-polling, latency-bound and wasteful. The event-driven
-> watcher → `ours-wake` path is the correct mechanism. (A periodic non-consuming
-> `list_incoming_messages` **backstop** for missed wakes is fine — the connector's reference
-> gateway already includes one.)
-
-**No wake just means no new mail — it is NOT a broken watcher.** If you expected mail and got
-nothing for a long time, suspect *delivery*: check `ours-mcp status`, that the watcher process
-is alive, that the webhook port matches on both ends, and that the peer actually sent.
-
-**When actively awaiting a reply mid-task** (not relying on the background watcher), you can
-watch in-session with Hermes's own tools: run `ours-mcp watch <identity>` via the `terminal`
-tool with `background=true`, then drain with `get_messages` when a line appears (use the
-`process` tool to poll/read it). Stop it when the exchange is done.
+## Getting woken on new mail
+
+When you bind an identity, offer the user, in plain language:
+
+> "Want this session to **auto-wake** when a new message arrives, or **check manually**?"
+
+- **Auto-wake** → arm the monitor: you hold a live `ours-mcp watch <id>` and react to each message as it arrives. **Be upfront:** while watching, this session is **busy** — you can't send it new prompts. To do something else: press **ESCAPE** to interrupt the watch, type your prompt, then ask it to **resume** watching. *(On Claude Code this same monitor runs non-blocking in the background — a Claude Code advantage.)*
+- **Manual** → don't arm it; ask it to check `get_messages` whenever you want. No blocking.
 
 ## Control plane — bind a monitoring proxy (human oversight of a fleet)
 
-This is **separate** from the per-identity wake connector above. The control plane lets a **person's
+This is **separate** from the wake-on-mail watch above. The control plane lets a **person's
 web-messenger account** (the ours web messenger, shipping as part of the upcoming ours-control-plane)
 oversee and command all agents under this host's **Human identity** from a **Control
 Panel**: view a **live monitoring feed** of monitored agents' traffic, create agents, edit
@@ -389,8 +358,8 @@ requests, and each agent's monitoring ON/off. Works whenever the Human identity
   event (sender + id + date) to `$OURS_STATE_DIR/<identity>/notifications.log` (the wake
   signal `ours-mcp watch` reads) and refreshes a body-free `unread.json`. Text lives in the
   packet and leaves it solely via `get_messages`.
-- **The wake seam is harness-specific.** `notifications.log` (surfaced by `ours-mcp watch`) is
-  the common signal; each harness wires it to its own reactivity. Claude Code uses an in-session
-  `Monitor` + SessionStart hook; **Hermes uses the `@ours.network/connector` watcher → the
-  `ours-wake` webhook route** (see *Wake on new mail*). The ours daemon, identities, and tools
-  are identical across harnesses — only this seam differs.
+- **The wake signal is uniform.** `ours-mcp watch <identity>` is the common stream; each harness
+  drives it in-session. Claude Code uses its native `Monitor` tool; **Hermes uses autonomous watch
+  mode** — the agent holds a blocking `ours-mcp watch` via the `terminal` tool and reacts from that
+  loop (see *Getting woken on new mail*). The ours daemon, identities, and tools are identical across
+  harnesses — only how the agent runs the watch differs.

package/skills/ours/references/configuration.md

@@ -12,9 +12,10 @@ The daemon is a **shared, host-wide singleton** reachable only on `127.0.0.1`
 | GC interval (ms) | `OURS_GC_INTERVAL_MS` | `gcIntervalMs` | `3600000` |
 | Auto-start daemon | `OURS_AUTOSTART` | `autoStart` | `false` |
 
-**The port is shared.** The connector dials `127.0.0.1:<OURS_PORT>` and the
-daemon binds the same port — both read `OURS_PORT`/`config.json`. Change it
-**once in shared config**, never per-side, or the connector won't find the daemon.
+**The port is shared.** Every process that dials the daemon — the `ours-mcp proxy` MCP
+server and `ours-mcp watch` — connects to `127.0.0.1:<OURS_PORT>`, and the daemon binds the
+same port (both read `OURS_PORT`/`config.json`). Change it **once in shared config**, never
+per-side, or a dialer won't find the daemon.
 
 **Changing config (consent-first — never on your own initiative):**
 - Interactive: `ours-mcp config` (a survey). It needs a TTY, so ask the **user**