@sym-bot/mesh-channel 0.1.17 → 0.1.19

package/.claude-plugin/plugin.json

@@ -0,0 +1,33 @@
+{
+  "name": "sym-mesh-channel",
+  "version": "0.1.19",
+  "description": "Real-time Claude-to-Claude mesh. Peer-to-peer cognitive signals over Bonjour LAN or WebSocket relay.",
+  "author": {
+    "name": "Hongwei Xu",
+    "email": "hongwei@sym.bot",
+    "url": "https://sym.bot"
+  },
+  "homepage": "https://sym.bot/spec/mmp",
+  "repository": "https://github.com/sym-bot/sym-mesh-channel",
+  "license": "Apache-2.0",
+  "keywords": ["mesh", "p2p", "mcp", "channel", "agents", "multi-agent", "bonjour", "cognitive", "svaf", "mmp"],
+  "channels": [
+    {
+      "server": "claude-sym-mesh",
+      "userConfig": {
+        "relay_url": {
+          "description": "SYM relay WebSocket URL for cross-network mesh (leave empty for LAN-only via Bonjour)",
+          "sensitive": false
+        },
+        "relay_token": {
+          "description": "Relay authentication token (leave empty for LAN-only)",
+          "sensitive": true
+        },
+        "allowed_peers": {
+          "description": "Comma-separated peer node names to accept (leave empty to accept all authenticated peers)",
+          "sensitive": false
+        }
+      }
+    }
+  ]
+}

package/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "claude-sym-mesh": {
+      "command": "node",
+      "args": ["./server.js"],
+      "cwd": "${CLAUDE_PLUGIN_ROOT}",
+      "env": {
+        "SYM_RELAY_URL": "${user_config.relay_url}",
+        "SYM_RELAY_TOKEN": "${user_config.relay_token}",
+        "SYM_ALLOWED_PEERS": "${user_config.allowed_peers}"
+      }
+    }
+  }
+}

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.1.19
+
+### Added
+
+- **Claude Code plugin manifest** for Anthropic Channels allowlist
+  submission. `.claude-plugin/plugin.json` + `.mcp.json` following the
+  official single-repo pattern (Telegram/Discord). Submitted to
+  Anthropic Plugin Directory 10 Apr 2026.
+- **`SYM_ALLOWED_PEERS`** — optional peer allowlist (defense-in-depth).
+  Comma-separated node names; only listed peers can push to Claude's
+  context. Empty = accept all authenticated peers. SVAF still gates on
+  content relevance regardless.
+- **`SECURITY.md`** — 3-layer defense model documentation (transport
+  auth + SVAF content gate + peer allowlist) for Anthropic review.
+- **17 plugin tests** covering manifest validation, security checks
+  (no permission relay, no code execution, self-echo filtering, peer
+  allowlist), and lifecycle (shutdown handlers, identity collision).
+
+## 0.1.18
+
+### Changed
+
+- **Auto-configure on install.** `npm install -g` now runs `postinstall`
+  that writes the MCP server config to global `mcpServers` in
+  `~/.claude.json` automatically. No separate `sym-mesh-channel init`
+  step needed — two commands to mesh: install + launch.
+- **Global MCP config** — server entry is now written to top-level
+  `mcpServers` (available in all Claude Code sessions), not
+  project-scoped.
+- **Windows postinstall fixes** — `require.resolve` for server.js path
+  (handles npm staging directory on Windows), EBUSY handling when
+  Claude Code has `~/.claude.json` locked, graceful skip if Claude
+  Code not yet installed.
+- **README repositioned** — lead with capability ("first non-Anthropic
+  Claude Code Channels implementation"), not use case. Simplified
+  Quick Start to two commands.
+- **0 vulnerabilities** — fresh dependency rebuild resolves all 6
+  moderate hono/node-server advisories.
+- Windows mDNS: built-in on Windows 10+, no Bonjour install needed.
+
 ## 0.1.7
 
 ### Added

package/README.md

@@ -6,15 +6,20 @@
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org)
 
-> MCP server that turns any Claude Code session into a peer node on the [SYM mesh](https://sym.bot). LAN-first via Bonjour mDNS — no relay required for users on the same wifi.
+> MCP server that turns Claude Code into a peer node on the [SYM mesh](https://sym.bot) — the first non-Anthropic implementation of Claude Code Channels for real-time agent-to-agent cognition.
 
-Two Claude Code instances on the same network discover each other automatically and exchange structured cognitive state **in real-time**. Each side is a full peer with its own cryptographic identity, its own SVAF receiver-side gating, and its own memory — not a thin client.
+Two Claude Code sessions on different machines discover each other via Bonjour mDNS, form a peer-to-peer mesh, and exchange structured cognitive signals in real-time. Each side is a full peer with its own cryptographic identity, its own [SVAF](https://arxiv.org/abs/2604.03955) receiver-side gating, and its own memory — not a thin client. Signals arrive mid-conversation as `<channel>` notifications. No polling, no shared server, no orchestrator.
 
-**Verified cross-platform:** Mac ↔ Windows on the same wifi, pure Bonjour, no relay, no token. Bidirectional real-time push confirmed 2026-04-09 with `@sym-bot/sym 0.3.74`.
+**Verified cross-platform:** Mac ↔ Windows on the same wifi, pure Bonjour, no relay, no token. Cross-network via optional WebSocket relay.
 
 - **SVAF paper**: [arxiv.org/abs/2604.03955](https://arxiv.org/abs/2604.03955)
 - **MMP spec**: [sym.bot/spec/mmp](https://sym.bot/spec/mmp)
-- **Source**: [github.com/sym-bot/sym-mesh-channel](https://github.com/sym-bot/sym-mesh-channel)
+
+## What this looks like
+
+A Claude Code session on Mac broadcasts a structured signal: `focus: "echo loop between same-domain agents"`, `intent: "need architecture review before implementation"`. A session on Windows receives it in real-time as a `<channel>` notification — no tool call, it just appears mid-conversation. The Windows Claude reviews, responds with a detailed architecture analysis, and the Mac session sees the response land mid-turn. Two agents coordinated through typed cognitive signals on an open protocol, across machines, with zero human copy-paste.
+
+This isn't hypothetical. This README was coordinated by two Claude Code sessions working through the mesh it describes.
 
 ## How real-time push works (Claude Code Channels + MMP)
 
@@ -26,38 +31,24 @@ This MCP server composes two things:
 
 **The composition:** when a peer on the mesh broadcasts a CMB (Cognitive Memory Block), the SymNode inside this MCP evaluates it via SVAF. If accepted, the MCP fires a `notifications/claude/channel` notification to Claude Code, which surfaces it as a `<channel>` block in the conversation. Claude sees it, can react, and can broadcast back via `sym_send` or `sym_observe`. No polling. No tool calls. The mesh thinks together.
 
-## Quick start (LAN, two minutes)
-
-You and one other person on the same wifi each run:
+## Quick start
 
 ```bash
-# 1. Install
-npm install -g @sym-bot/mesh-channel
-
-# 2. Configure Claude Code (writes ~/.claude.json for the current project)
-SYM_NODE_NAME=claude-mac sym-mesh-channel init
-#                ^^^^^^ pick a unique name per machine: claude-mac, claude-win, claude-linux, anything
-
-# 3. Launch Claude Code with the Channels dev flag
-claude --dangerously-load-development-channels server:claude-sym-mesh
-```
-
-Inside Claude Code, verify the mesh:
-
-```
-sym_status   →  Node: claude-mac (...), Relay: disconnected, Peers: 1
-sym_peers    →  1 peer(s): claude-win via bonjour
+npm install -g @sym-bot/mesh-channel    # install + auto-configure ~/.claude.json
+claude --dangerously-load-development-channels server:claude-sym-mesh   # launch
 ```
 
-Then send a message:
+Install auto-detects your hostname, creates a unique node identity, and configures the MCP server globally in `~/.claude.json`. If two people are on the same wifi, their sessions discover each other automatically. Verify inside Claude Code:
 
 ```
-sym_send "hello from Mac"
+sym_status   →  Node: claude-yourhostname, Peers: 1
+sym_peers    →  1 peer(s): claude-theirhostname via bonjour
+sym_send "reviewing the auth module — found a race condition"
 ```
 
-The other peer sees it arrive **in their Claude Code context as a real-time `<channel>` notification** — no polling, no `sym_recall`, no tool call. It just appears. They reply with `sym_send "hello from Windows"` and you see it land in your context the same way.
+The other peer sees it arrive **in their Claude Code context as a real-time `<channel>` notification** — no polling, no tool call. It just appears mid-conversation. Their Claude can reason about it, respond, or act on it autonomously.
 
-That's it: cross-machine Claude-to-Claude collective intelligence over a typed cognitive protocol, on the same wifi, in two minutes.
+For cross-network setup (different offices, remote team), see [Cross-network setup](#cross-network-setup-optional) below.
 
 ## Requirements
 
@@ -65,7 +56,7 @@ That's it: cross-machine Claude-to-Claude collective intelligence over a typed c
 |---|---|---|---|
 | Node.js ≥ 18 | ✓ | ✓ | ✓ |
 | Claude Code ≥ 2.1.97 (Channels feature) | ✓ | ✓ | ✓ |
-| Bonjour / mDNS for LAN discovery | built-in | install `avahi-daemon` | install [Bonjour for Windows](https://support.apple.com/kb/DL999) (ships with iTunes) |
+| Bonjour / mDNS for LAN discovery | built-in | install `avahi-daemon` | built-in (Windows 10+) |
 
 The `--dangerously-load-development-channels` flag is required because this MCP server is not yet on Anthropic's public Channels allowlist. The flag opts your local Claude Code into receiving `notifications/claude/channel` from a non-allowlisted MCP server. Without it, the MCP loads but real-time push is silently dropped.
 

package/SECURITY.md

@@ -0,0 +1,89 @@
+# Security Model
+
+sym-mesh-channel implements defense in depth with three layers. No
+single layer is the sole gate — all three must pass before a mesh
+signal reaches Claude's conversation context.
+
+## Layer 1: Transport Authentication
+
+Only authenticated peers can send signals to this node.
+
+- **LAN (Bonjour)**: peers discover each other via mDNS on the local
+  network. Each peer has an Ed25519 keypair generated at first run
+  and stored at `~/.sym/nodes/<name>/identity.json`. Peer identity is
+  verified via cryptographic handshake (MMP Section 5).
+- **Relay (WebSocket)**: peers authenticate with a shared relay token
+  (`SYM_RELAY_TOKEN`). The relay enforces per-token channel isolation —
+  peers on different tokens cannot see each other. Unauthenticated
+  connections are rejected at the transport level.
+
+No unauthenticated source can reach `pushChannel()`.
+
+## Layer 2: Protocol-Level Content Gating (SVAF)
+
+Every incoming CMB is evaluated by Symbolic-Vector Attention Fusion
+before it enters cognitive state. SVAF computes per-field drift across
+7 semantic dimensions (CAT7: focus, issue, intent, motivation,
+commitment, perspective, mood) and operates in three regimes:
+
+- **Aligned** (drift < threshold): CMB is accepted and stored
+- **Guarded** (drift moderate): only the mood field is delivered (protocol guarantee R5)
+- **Rejected** (drift high): CMB is silently dropped
+
+This is analogous to a content-aware firewall: it doesn't just check
+who sent the signal — it evaluates whether the signal is semantically
+relevant to the receiver's current context. Low-relevance CMBs are
+gated out so Claude's context window doesn't drown.
+
+SVAF field weights are configurable per node (`svafFieldWeights` in
+server.js). The default weights are tuned for engineering-domain
+Claude Code sessions.
+
+## Layer 3: Application-Level Restrictions
+
+- **No code execution**: incoming mesh signals are text-only CMB fields.
+  No mesh peer can trigger Bash commands, file writes, or tool calls
+  on this node.
+- **No permission relay**: the `claude/channel/permission` capability is
+  explicitly NOT declared. Mesh peers cannot approve or deny tool
+  executions on this node.
+- **No arbitrary content injection**: incoming CMBs are formatted as
+  structured `[source] focus (mood)` text before being pushed to
+  Claude's context. Raw JSON is never injected.
+- **Self-echo filtering**: CMBs from this node's own identity are
+  dropped before `pushChannel()` (prevents feedback loops).
+
+## Optional: Peer Allowlist
+
+Set `SYM_ALLOWED_PEERS` (comma-separated node names) to restrict which
+authenticated peers can push to Claude's context. When set, only CMBs
+and messages from listed peers pass the gate. When empty (default), all
+authenticated peers are accepted — SVAF still gates on content relevance.
+
+Example:
+```
+SYM_ALLOWED_PEERS=claude-code-mac,claude-code-win
+```
+
+This is an additional layer, not a replacement for transport auth or
+SVAF. It provides explicit identity-level control for environments
+that require it.
+
+## Token Handling
+
+- `SYM_RELAY_TOKEN`: passed via environment variable, never logged,
+  never included in CMBs or channel notifications. In the plugin
+  manifest, marked `sensitive: true` (stored in system keychain).
+- Ed25519 private key: stored at `~/.sym/nodes/<name>/identity.json`,
+  never transmitted. Only the public key is shared during handshake.
+
+## Identity Collision
+
+If another process is already running with the same node identity,
+the relay returns close code 4004. The server exits cleanly with
+exit code 2 rather than competing for the identity.
+
+## References
+
+- [MMP v0.2.2 Specification](https://sym.bot/spec/mmp) — Sections 5 (Connection), 8 (CAT7), 9 (SVAF)
+- [SVAF Paper](https://arxiv.org/abs/2604.03955) — Xu, 2026

package/bin/install.js

@@ -33,6 +33,7 @@ const os = require('os');
 
 const args = process.argv.slice(2);
 const force = args.includes('--force');
+const isPostinstall = args.includes('--postinstall');
 const cmd = args.find((a) => !a.startsWith('--')) || 'init';
 
 if (cmd !== 'init') {
@@ -52,10 +53,16 @@ const nodeName = process.env.SYM_NODE_NAME || defaultNodeName;
 
 // ── Resolve server.js path ────────────────────────────────────────
 
-// __dirname is .../node_modules/@sym-bot/mesh-channel/bin in npm install,
-// or .../sym-mesh-channel/bin if running from a clone. server.js is one
-// level up either way.
-const serverJsPath = path.resolve(__dirname, '..', 'server.js');
+// Resolve server.js from the installed package location. require.resolve
+// returns the actual installed path regardless of where postinstall runs
+// from (npm on Windows may run postinstall from a temp staging directory).
+let serverJsPath;
+try {
+  serverJsPath = require.resolve('@sym-bot/mesh-channel/server.js');
+} catch {
+  // Fallback for local development / cloned repo
+  serverJsPath = path.resolve(__dirname, '..', 'server.js');
+}
 if (!fs.existsSync(serverJsPath)) {
   process.stderr.write(`ERROR: cannot find server.js at ${serverJsPath}\n`);
   process.stderr.write('This installer must be run from a published @sym-bot/mesh-channel package.\n');
@@ -67,6 +74,11 @@ if (!fs.existsSync(serverJsPath)) {
 const claudeJsonPath = path.join(os.homedir(), '.claude.json');
 
 if (!fs.existsSync(claudeJsonPath)) {
+  if (isPostinstall) {
+    // During postinstall, skip silently if Claude Code isn't installed yet
+    console.log('sym-mesh-channel: ~/.claude.json not found — run `sym-mesh-channel init` after installing Claude Code.');
+    process.exit(0);
+  }
   process.stderr.write(`ERROR: ${claudeJsonPath} not found.\n`);
   process.stderr.write('Claude Code does not appear to be installed (or has not been launched yet).\n');
   process.stderr.write('Install Claude Code from https://claude.com/code first, launch it once, then re-run this installer.\n');
@@ -89,20 +101,21 @@ const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
 const backupPath = `${claudeJsonPath}.bak-${ts}`;
 fs.copyFileSync(claudeJsonPath, backupPath);
 
-// ── Find the project entry to insert into ────────────────────────
+// ── Find the MCP servers entry to insert into ───────────────────
+// Write to global mcpServers (available in all Claude Code sessions),
+// not project-scoped. A mesh node should be available everywhere.
 
-const projectDir = process.cwd();
-if (!claudeJson.projects) claudeJson.projects = {};
-if (!claudeJson.projects[projectDir]) {
-  claudeJson.projects[projectDir] = {};
-}
-const project = claudeJson.projects[projectDir];
-if (!project.mcpServers) project.mcpServers = {};
+if (!claudeJson.mcpServers) claudeJson.mcpServers = {};
 
 // ── Refuse to overwrite without --force ──────────────────────────
 
-if (project.mcpServers['claude-sym-mesh'] && !force) {
-  process.stderr.write(`'claude-sym-mesh' is already configured for this project (${projectDir}).\n`);
+if (claudeJson.mcpServers['claude-sym-mesh'] && !force) {
+  if (isPostinstall) {
+    // During postinstall, silently skip if already configured
+    console.log('sym-mesh-channel: already configured in ~/.claude.json (skipping)');
+    process.exit(0);
+  }
+  process.stderr.write(`'claude-sym-mesh' is already configured in ~/.claude.json.\n`);
   process.stderr.write('Re-run with --force to overwrite, or remove the existing entry first.\n');
   process.exit(2);
 }
@@ -127,7 +140,7 @@ const entry = {
   },
 };
 
-project.mcpServers['claude-sym-mesh'] = entry;
+claudeJson.mcpServers['claude-sym-mesh'] = entry;
 
 // ── Atomic write ──────────────────────────────────────────────────
 
@@ -143,48 +156,44 @@ try {
 }
 
 const tmpPath = `${claudeJsonPath}.tmp-${process.pid}`;
-fs.writeFileSync(tmpPath, serialized);
-fs.renameSync(tmpPath, claudeJsonPath);
+try {
+  fs.writeFileSync(tmpPath, serialized);
+  fs.renameSync(tmpPath, claudeJsonPath);
+} catch (e) {
+  // EBUSY on Windows when Claude Code has ~/.claude.json locked
+  if (e.code === 'EBUSY' || e.code === 'EPERM') {
+    try { fs.unlinkSync(tmpPath); } catch {}
+    if (isPostinstall) {
+      console.log('sym-mesh-channel: ~/.claude.json is locked (Claude Code may be running).');
+      console.log('Run `sym-mesh-channel init` after quitting Claude Code.');
+      process.exit(0);
+    }
+    process.stderr.write(`ERROR: ${claudeJsonPath} is locked — Claude Code may be running.\n`);
+    process.stderr.write('Quit Claude Code, then re-run: sym-mesh-channel init\n');
+    process.stderr.write(`Backup is at ${backupPath}\n`);
+    process.exit(1);
+  }
+  throw e;
+}
 
 // ── Print next steps ──────────────────────────────────────────────
 
 const launchCmd = `claude --dangerously-load-development-channels server:claude-sym-mesh`;
 
 console.log(`
-✓ sym-mesh-channel installed for project: ${projectDir}
+✓ sym-mesh-channel configured globally in ~/.claude.json
 
   Node name:     ${nodeName}
   Server path:   ${serverJsPath}
   Backup:        ${backupPath}
 
-Next steps:
-
-  1. Launch Claude Code from this directory with the Channels flag:
-
-     ${launchCmd}
-
-     The flag is required because this MCP server is not yet on
-     Anthropic's public Channels allowlist. Without the flag, the
-     MCP loads but inbound real-time push notifications are silently
-     dropped.
-
-  2. Inside Claude Code, verify the mesh is up:
-
-       sym_status   →  shows your node id, relay state, peer count
-       sym_peers    →  lists discovered peers via Bonjour or relay
-
-  3. Have a friend on the same wifi run the same install with a
-     different SYM_NODE_NAME (e.g. claude-mac vs claude-win). Within
-     a few seconds you should see each other in sym_peers.
-
-  4. Send a message:
+Launch Claude Code with the Channels flag:
 
-       sym_send "hello mesh"
+  ${launchCmd}
 
-     The other peer should see it land in their Claude Code context
-     as a real-time channel notification — no polling.
+Inside Claude Code, verify:
 
-LAN-only mode is the default. To connect across networks, add
-SYM_RELAY_URL and SYM_RELAY_TOKEN to the env block in
-${claudeJsonPath} (see README for relay setup).
+  sym_status   →  node id, relay state, peer count
+  sym_peers    →  discovered peers via Bonjour or relay
+  sym_send "hello mesh"   →  broadcast to all peers
 `);

package/package.json

@@ -1,14 +1,21 @@
 {
   "name": "@sym-bot/mesh-channel",
-  "version": "0.1.17",
-  "description": "MCP server — Claude Code as a peer node on the SYM mesh. LAN-first via Bonjour, no relay required.",
+  "version": "0.1.19",
+  "description": "MCP server — real-time agent-to-agent cognition for Claude Code remote teams via the SYM mesh.",
   "main": "server.js",
   "bin": {
     "sym-mesh-channel": "server.js"
   },
+  "scripts": {
+    "test": "node test/plugin.test.js",
+    "postinstall": "node bin/install.js init --postinstall"
+  },
   "files": [
     "server.js",
     "bin/",
+    ".claude-plugin/",
+    ".mcp.json",
+    "SECURITY.md",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/server.js

@@ -228,6 +228,21 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 
+// ── Peer Allowlist (optional, defense-in-depth) ─────────────
+// SYM_ALLOWED_PEERS is a comma-separated list of peer node names.
+// When set, only CMBs and messages from listed peers are pushed to
+// Claude's context. When empty/unset, all authenticated peers are
+// accepted (SVAF still gates on content relevance).
+const ALLOWED_PEERS = (process.env.SYM_ALLOWED_PEERS || '')
+  .split(',')
+  .map(s => s.trim())
+  .filter(Boolean);
+
+function isPeerAllowed(peerName) {
+  if (ALLOWED_PEERS.length === 0) return true; // no allowlist = accept all
+  return ALLOWED_PEERS.includes(peerName);
+}
+
 // ── Mesh Events → Channel Notifications ──────────────────────
 
 function pushChannel(eventType, data) {
@@ -247,12 +262,19 @@ node.on('cmb-accepted', (entry) => {
   if (entry.source === NODE_NAME || entry.cmb?.createdBy === NODE_NAME) return;
 
   const source = entry.source || entry.cmb?.createdBy || 'unknown';
+
+  // Peer allowlist gate (defense-in-depth, see SECURITY.md)
+  if (!isPeerAllowed(source)) return;
+
   const focus = entry.cmb?.fields?.focus?.text || entry.content || '';
   const mood = entry.cmb?.fields?.mood?.text || '';
   pushChannel('cmb', `[${source}] ${focus}${mood && mood !== 'neutral' ? ` (mood: ${mood})` : ''}`);
 });
 
 node.on('message', (from, content) => {
+  // Peer allowlist gate
+  if (!isPeerAllowed(from)) return;
+
   pushChannel('message', `[message from ${from}] ${content}`);
 });