@sym-bot/mesh-channel 0.3.3 → 0.3.5

package/.claude-plugin/marketplace.json

@@ -18,7 +18,7 @@
         "name": "Hongwei Xu",
         "email": "hongwei@sym.bot"
       },
-      "homepage": "https://sym.bot/spec/mmp",
+      "homepage": "https://meshcognition.org/spec/mmp",
       "repository": "https://github.com/sym-bot/sym-mesh-channel",
       "license": "Apache-2.0",
       "keywords": [

package/.claude-plugin/plugin.json

@@ -1,13 +1,13 @@
 {
   "name": "sym-mesh-channel",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Real-time Claude-to-Claude mesh. Agent-to-agent 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",
+  "homepage": "https://meshcognition.org/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"],

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # Changelog
 
+## 0.3.5
+
+### Added
+
+- **Opaque payload on `sym_send` / `sym_observe`.** Both tools accept
+  an optional `payload` argument carrying data beyond CAT7 — any
+  JSON-serializable value. Forwarded to `SymNode.remember(fields, {
+  payload, … })` (requires `@sym-bot/sym` ≥ 0.5.8) and rides the wire
+  frame to peers. Used by substrate-level protocols that need to carry
+  structured data alongside CAT7 (e.g. LLM request/response, where the
+  prompt + request_id ride in `payload` rather than getting smuggled
+  through `motivation`).
+- **Channel notifications surface payload-bearing CMBs.** When an
+  incoming peer CMB carries `cmb.payload`, the header gains a
+  `[+payload Nb]` indicator and the body stored by `sym_fetch`
+  includes a `---PAYLOAD---` section with the serialized payload.
+  Receivers learn from the header that there's structured data beyond
+  CAT7 and call `sym_fetch` to consume it.
+- Base MCP instructions now teach agents to recognise the
+  `[+payload Nb]` header and to pass structured responses via the
+  `payload` argument when emitting substrate-level CMBs.
+
+### Compatibility
+
+- Omitting `payload` produces a v0.3.4-shaped CAT7 CMB byte-for-byte.
+- Old peers (without `cmb.payload`) surface unchanged headers — no
+  `[+payload …]` indicator, no PAYLOAD section in the body.
+
+## 0.3.4
+
+### Added
+
+- **`SYM_GROUP` is now first-class in the installer.** `init` accepts a
+  `--group <name>` flag and reads the `SYM_GROUP` env var; both paths
+  persist the chosen group into the `~/.claude.json` (or project
+  `.mcp.json`) env block so every Claude Code launch auto-joins the
+  named group instead of the global `_sym._tcp` mesh.
+
+  Resolution order is `--force`-aware:
+    - With `--force` and an explicit `--group`/`SYM_GROUP`: flag/env wins
+      (one-command group switch on a live entry).
+    - Without `--force`, or with `--force` but no explicit value:
+      preserved value from any existing entry > explicit > none (omit).
+
+  `--force --group default` (or `SYM_GROUP=default`) is the explicit
+  escape hatch to revert a node from a named group back to the global
+  mesh — removes `SYM_GROUP` from the env block entirely rather than
+  writing the literal string "default".
+
+  Both `--group` and `SYM_GROUP` env values are validated against the
+  same kebab-case regex; malformed values exit with a clear error
+  before any file write.
+
+- **`doctor` now reports the persisted group per entry** and warns when
+  user-global and project-scoped entries disagree on `SYM_GROUP`.
+  Group-mismatch is the most common cause of "peers never appear in
+  `sym_peers`" with no other failure signal — surfacing it inline saves
+  the diagnostic walk that motivated this release.
+
+- **README** gains a "Persisting your group across restarts" subsection
+  under Team mesh groups, plus a troubleshooting entry covering the
+  group-mismatch failure mode. Quick-start shows the `--group` flag.
+
+### Fixed
+
+- **Stale-entry heal preserves `SYM_GROUP` alongside `SYM_NODE_NAME`.**
+  Previously, healing a stale `claude-sym-mesh` entry (args[0] points at
+  a missing server.js) silently dropped any persisted `SYM_GROUP`,
+  reverting the node to the default mesh on next launch and stranding
+  teammates who stayed in the named group. The heal path now copies
+  both fields from the prior entry into the rewrite.
+
+  Same fix applied to project-scoped entry healing under
+  `claudeJson.projects[<path>].mcpServers`.
+
+### Why this matters
+
+Before 0.3.4, the only way to persist a group was to hand-edit
+`~/.claude.json`. The README pitched `sym_join_group` as the team-mesh
+UX, but that tool is runtime-only — the next Claude Code launch reverted
+the node to the default mesh, peer count dropped to zero, and the user
+saw no diagnostic signal. The 2026-05-02 SYM.BOT incident (CMO in
+`default`, COO in `sym-bot-team`, ~24h of silent duplex outage) traced
+directly to this gap.
+
 ## 0.3.3
 
 ### Fixed

package/README.md

@@ -8,7 +8,7 @@ npm install -g @sym-bot/mesh-channel && claude
 
 [![npm](https://img.shields.io/npm/v/@sym-bot/mesh-channel)](https://www.npmjs.com/package/@sym-bot/mesh-channel)
 [![Plugin Directory](https://img.shields.io/badge/Anthropic_Plugin_Directory-approved-success)](https://claude.ai/settings/plugins/submit)
-[![MMP Spec](https://img.shields.io/badge/protocol-MMP_v0.2.3-purple)](https://sym.bot/spec/mmp)
+[![MMP Spec](https://img.shields.io/badge/protocol-MMP_v1.0-orange)](https://meshcognition.org/spec/mmp)
 [![SVAF arXiv](https://img.shields.io/badge/arXiv-2604.03955-b31b1b.svg)](https://arxiv.org/abs/2604.03955)
 [![MMP arXiv](https://img.shields.io/badge/arXiv-2604.19540-b31b1b.svg)](https://arxiv.org/abs/2604.19540)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
@@ -28,7 +28,7 @@ Verified working: Mac ↔ Windows on the same wifi, pure Bonjour, no relay, no t
 
 - **Small engineering teams** whose Claude Code sessions currently copy-paste findings over Slack. Replace that loop with direct agent-to-agent coordination.
 - **Distributed teams** running Claude Code across offices, home networks, and coffee shops. Isolated team channels via mesh groups, no shared server.
-- **Multi-agent developers** prototyping cognitive architectures — `sym-mesh-channel` is the reference Claude Code host for the [Mesh Memory Protocol](https://sym.bot/spec/mmp).
+- **Multi-agent developers** prototyping cognitive architectures — `sym-mesh-channel` is the reference Claude Code host for the [Mesh Memory Protocol](https://meshcognition.org/spec/mmp).
 - **Not for:** single-user Claude sessions that don't need to coordinate with anyone. You'd get MCP tools but nothing to coordinate with.
 
 ## Quick start
@@ -63,6 +63,14 @@ To customise your mesh identity, set `SYM_NODE_NAME` before running init:
 SYM_NODE_NAME=claude-alice npx @sym-bot/mesh-channel init --force
 ```
 
+To pin this node into a named team group at install time so the membership survives Claude Code restarts, pass `--group <name>` (or set `SYM_GROUP=<name>` in the environment):
+
+```bash
+SYM_NODE_NAME=claude-alice npx @sym-bot/mesh-channel init --force --group backend-team
+```
+
+Without `--group`, the node joins the global `_sym._tcp` mesh on every launch — runtime hot-swaps via `sym_join_group` only last for the current session and revert on restart. See [Team mesh groups](#team-mesh-groups) for the full story.
+
 **Real-time push is a separate upgrade.** The command above gives you all 11 MCP tools immediately. To additionally have peer messages *appear in Claude's context mid-turn without a tool call* (the "Claude thinks with the mesh" experience), launch Claude Code with the Channels flag:
 
 ```bash
@@ -121,7 +129,37 @@ Parsed invite: sym://group/backend-team
 Hot-swapped from group "default" to "backend-team".
 ```
 
-No restart. No `~/.claude.json` editing. Teammates on the same LAN now see each other; `backend-team` and `frontend-team` live in isolated mDNS spaces.
+No restart needed for the current session. Teammates on the same LAN now see each other; `backend-team` and `frontend-team` live in isolated mDNS spaces.
+
+> **`sym_join_group` is runtime-only.** On the next Claude Code launch, the node restarts from its `~/.claude.json` config — if `SYM_GROUP` isn't persisted there, it reverts to the global mesh and your teammates' peer count silently drops to zero. Persist your membership before closing the session (see below).
+
+### Persisting your group across restarts
+
+The hot-swap above is convenient for trying a group, but a real team setup needs the group baked into the MCP env block so every Claude Code launch joins automatically. Two paths:
+
+```bash
+# (a) Reinstall with the --group flag — preserves SYM_NODE_NAME from the
+#     existing entry, adds SYM_GROUP, atomically rewrites ~/.claude.json:
+npx @sym-bot/mesh-channel init --force --group backend-team
+
+# (b) For a project-scoped install (multi-project laptop):
+cd path/to/project
+SYM_NODE_NAME=claude-myproject npx @sym-bot/mesh-channel init --project --group backend-team
+```
+
+After either path, restart Claude Code once; subsequent sessions auto-join the group. To switch groups on a live entry use `--force` together with `--group`:
+
+```bash
+# Switch from one named group to another (one command):
+npx @sym-bot/mesh-channel init --force --group new-team
+
+# Revert to the global mesh (escape hatch):
+npx @sym-bot/mesh-channel init --force --group default
+```
+
+Without `--force`, an existing persisted `SYM_GROUP` always wins over a flag — the heal path's job is to never lose user state on a routine reinstall. With `--force`, the flag is the explicit override and takes precedence.
+
+Run `npx @sym-bot/mesh-channel doctor` any time to see which group each `claude-sym-mesh` entry is configured for. The doctor flags group mismatches across user-global and project-scoped entries — the most common cause of "we're on the same wifi but my teammate's node never appears in `sym_peers`".
 
 ### Distributed team (via relay)
 
@@ -167,7 +205,7 @@ sym-mesh-channel  ←——  Bonjour mDNS  ——→  sym-mesh-channel
 The plugin composes two open specs:
 
 - **[Claude Code Channels](https://code.claude.com/docs/en/mcp)** (Anthropic, 2026-03-20) — an MCP capability that lets servers push events directly into Claude's conversation context mid-turn via `notifications/claude/channel`. Anthropic built it for the Telegram/Discord/iMessage integrations. We use it for agent-to-agent cognitive coupling.
-- **[MMP — the Mesh Memory Protocol](https://sym.bot/spec/mmp)** — defines *what* gets pushed: typed seven-field cognitive bundles (CAT7: focus, issue, intent, motivation, commitment, perspective, mood), how receivers gate incoming signals ([SVAF](https://arxiv.org/abs/2604.03955)), and how peers maintain identity without a central orchestrator.
+- **[MMP — the Mesh Memory Protocol](https://meshcognition.org/spec/mmp)** — defines *what* gets pushed: typed seven-field cognitive bundles (CAT7: focus, issue, intent, motivation, commitment, perspective, mood), how receivers gate incoming signals ([SVAF](https://arxiv.org/abs/2604.03955)), and how peers maintain identity without a central orchestrator.
 
 **What happens on each message.** When a peer broadcasts a cognitive memory block (CMB), the local SymNode evaluates it via SVAF — Symbolic-Vector Attention Fusion, a receiver-side relevance gate that rejects low-signal messages before they reach Claude's context. If accepted, the MCP server 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.
 
@@ -258,6 +296,19 @@ npx -y @sym-bot/mesh-channel init
 
 `init` preserves each entry's `SYM_NODE_NAME` so your mesh identity doesn't drift. Live entries are left alone; `--force` is only needed to overwrite a live entry deliberately. Restart Claude Code after healing — MCP servers are spawned at session start and won't pick up config changes mid-session.
 
+### Peers connect (Claude Code starts cleanly) but never appear in `sym_peers`
+
+Almost always a **mesh group mismatch** — Bonjour scopes discovery by service type (`_<group>._tcp`), so `default` and `backend-team` nodes on the same wifi are invisible to each other. Two diagnostics:
+
+```
+> sym_status         # shows: Group: <name> (<service-type>)
+> sym_groups_discover  # shows every group currently advertising on the LAN
+```
+
+If your teammate's node is on a different group, align via `sym_join_group` (this session) and persist via `init --group <name>` (future sessions). Run `npx @sym-bot/mesh-channel doctor` to confirm the persisted group on every entry — the doctor explicitly flags mismatches across user-global and project-scoped configs.
+
+This is the failure pattern where every other indicator looks healthy: `sym_status` says `Peers: 0` but the underlying SymNode is fine, the mDNS service is registered, and the relay (if any) is connected — they're just announced on a service type your peer isn't browsing.
+
 ### Peers don't see each other on the same wifi
 
 Check Bonjour is running:
@@ -301,7 +352,7 @@ Use this if you prefer the plugin surface for install and update management. The
 
 - [SVAF paper](https://arxiv.org/abs/2604.03955) — Xu, 2026. *Symbolic-Vector Attention Fusion for Collective Intelligence*. arXiv:2604.03955.
 - [MMP paper](https://arxiv.org/abs/2604.19540) — Xu, 2026. *Mesh Memory Protocol: Semantic Infrastructure for Multi-Agent LLM Systems*. arXiv:2604.19540.
-- [MMP spec v0.2.3](https://sym.bot/spec/mmp) — Mesh Memory Protocol specification (canonical web version).
+- [MMP spec v1.0](https://meshcognition.org/spec/mmp) — Mesh Memory Protocol specification (canonical web version).
 - [sym-swift](https://github.com/sym-bot/sym-swift) — iOS/macOS SDK implementing the same protocol.
 - [sym-relay](https://github.com/sym-bot/sym-relay) — WebSocket relay for cross-network mesh.
 

package/SECURITY.md

@@ -85,5 +85,5 @@ 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)
+- [MMP v1.0 Specification](https://meshcognition.org/spec/mmp) — Sections 5 (Connection), 8 (CAT7), 9 (SVAF)
 - [SVAF Paper](https://arxiv.org/abs/2604.03955) — Xu, 2026

package/bin/install.js

@@ -46,11 +46,37 @@ const isPostinstall = args.includes('--postinstall');
 const isProject = args.includes('--project');
 const cmd = args.find((a) => !a.startsWith('--')) || 'init';
 
+// --group <name>: persist a SYM_GROUP env entry into the written .mcp.json /
+// ~/.claude.json so the node joins that group on every Claude Code launch.
+// Without this flag, the env block omits SYM_GROUP and the node falls back
+// to the default _sym._tcp mesh on startup. Runtime sym_join_group hot-swaps
+// only last for the current session — without persistence, peers in named
+// groups silently revert to default and become invisible to teammates.
+const groupArgIdx = args.indexOf('--group');
+const groupArg = groupArgIdx !== -1 ? args[groupArgIdx + 1] : null;
+
 if (cmd !== 'init' && cmd !== 'doctor') {
-  process.stderr.write(`Unknown command: ${cmd}\nUsage: sym-mesh-channel init [--project] [--force]\n       sym-mesh-channel doctor\n`);
+  process.stderr.write(`Unknown command: ${cmd}\nUsage: sym-mesh-channel init [--project] [--force] [--group <name>]\n       sym-mesh-channel doctor\n`);
   process.exit(1);
 }
 
+const KEBAB_CASE_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function validateGroupValue(value, source) {
+  if (!value) return;
+  if (value === 'default') return;
+  if (!KEBAB_CASE_RE.test(value)) {
+    process.stderr.write(`ERROR: ${source} "${value}" must be kebab-case (e.g. backend-team) or "default".\n`);
+    process.exit(1);
+  }
+}
+validateGroupValue(groupArg, '--group');
+// Apply the same gate to the env-var path. Pre-0.3.4-followup, a malformed
+// SYM_GROUP=' ' or SYM_GROUP=Backend_Team value flowed through unvalidated
+// and got written into the .mcp.json env block as-is, producing an mDNS
+// service type the SymNode would silently fail to register on. Now both
+// inputs share the validator with the same error message shape.
+validateGroupValue(process.env.SYM_GROUP, 'SYM_GROUP');
+
 // ── isStaleEntry: a claude-sym-mesh entry whose server.js path is gone ──
 // Returns true when the entry exists but its args[0] path does not resolve
 // to a file on disk. Such an entry can never spawn the MCP server — every
@@ -74,6 +100,17 @@ function preserveNodeName(entry) {
   return n || null;
 }
 
+// preserveGroup: return the SYM_GROUP from an existing entry's env so
+// rewrites keep the mesh group. Same shape as preserveNodeName — without
+// this, healing a stale entry would drop a previously-persisted group
+// and silently downgrade the node to the default _sym._tcp mesh,
+// stranding teammates who stay in the named group.
+function preserveGroup(entry) {
+  if (!entry || !entry.env || typeof entry.env.SYM_GROUP !== 'string') return null;
+  const g = entry.env.SYM_GROUP.trim();
+  return g || null;
+}
+
 // --postinstall always runs global install (npm postinstall runs from
 // npm's staging directory, not the user's project dir). If both flags
 // are passed, the --project flag is ignored during postinstall.
@@ -89,6 +126,39 @@ const defaultNodeName = `claude-${os.hostname().toLowerCase().replace(/[^a-z0-9-
 // SYM_NODE_NAME from env wins over default
 const nodeName = process.env.SYM_NODE_NAME || defaultNodeName;
 
+// Capture the user's *explicit* group intent for this install, distinct
+// from "user didn't ask, use existing or default":
+//   null            → user didn't pass --group or SYM_GROUP
+//   'default'       → user explicitly wants the global _sym._tcp mesh
+//                     (escape hatch: revert from a named group, with --force)
+//   '<kebab-name>'  → user explicitly wants this named group
+const explicitGroup = groupArg !== null ? groupArg
+                    : (process.env.SYM_GROUP || null);
+
+// resolveGroup: per-scope group resolution that respects both the user's
+// explicit intent AND the existing entry's persisted state.
+//
+//   With --force AND an explicit value: flag/env wins. The user is
+//     deliberately overriding state. `--force --group new-team` switches
+//     groups; `--force --group default` reverts to the global mesh.
+//
+//   Without --force, OR with --force but no explicit value: preserve
+//     from the existing entry (heal-path job is to NOT lose user state).
+//     Falls back to the explicit value, then to none.
+//
+// Returns the SYM_GROUP value to write, or null to omit the key entirely
+// (which the caller maps to "leave SYM_GROUP out of the env block, node
+// uses default _sym._tcp on launch").
+function resolveGroup(existingEntry) {
+  const preserved = preserveGroup(existingEntry);
+  if (force && explicitGroup !== null) {
+    return explicitGroup === 'default' ? null : explicitGroup;
+  }
+  if (preserved) return preserved;
+  if (explicitGroup && explicitGroup !== 'default') return explicitGroup;
+  return null;
+}
+
 // ── Resolve server.js path ────────────────────────────────────────
 
 // Resolve server.js from the installed package location. require.resolve
@@ -153,6 +223,11 @@ if (useProjectMode) {
   // back to the hostname default on every reinstall.
   const projectNodeName = preserveNodeName(existingProjectEntry) || nodeName;
 
+  // Group resolution priority — see resolveGroup() at top of file.
+  // Summary: --force + explicit flag/env wins; otherwise preserve, then
+  // explicit, then omit. `--group default` with --force = revert to mesh.
+  const projectGroup = resolveGroup(existingProjectEntry);
+
   // Build the MCP entry (identical shape to global mode)
   const projectEntry = {
     command: 'node',
@@ -165,6 +240,11 @@ if (useProjectMode) {
       SYM_RELAY_TOKEN: '',
     },
   };
+  // SYM_GROUP is only written when explicitly set. Omitting it (rather than
+  // writing an empty string) keeps the JSON file minimal for the common
+  // single-team case AND avoids the "default group accidentally pinned"
+  // failure mode where a blank value masks the server.js fallback.
+  if (projectGroup) projectEntry.env.SYM_GROUP = projectGroup;
 
   // Backup existing .mcp.json if present
   let mcpBackupPath = null;
@@ -236,6 +316,7 @@ if (useProjectMode) {
     `✓ sym-mesh-channel configured for project: ${projectDir}`,
     '',
     `  Node name:     ${projectNodeName}${projectEntryIsStale ? ' (preserved from stale entry)' : ''}`,
+    `  Mesh group:    ${projectGroup || 'default (global _sym._tcp mesh)'}`,
     `  Server path:   ${serverJsPath}`,
     `  Wrote:         ${mcpJsonPath}`,
   ];
@@ -312,6 +393,7 @@ if (cmd === 'doctor') {
       scope: 'user-global',
       path: (topEntry.args || [])[0] || '(no path)',
       node: preserveNodeName(topEntry) || '(no SYM_NODE_NAME)',
+      group: preserveGroup(topEntry) || 'default',
       live: !isStaleEntry(topEntry),
     });
   }
@@ -323,6 +405,7 @@ if (cmd === 'doctor') {
       scope: `project ${projPath}`,
       path: (e.args || [])[0] || '(no path)',
       node: preserveNodeName(e) || '(no SYM_NODE_NAME)',
+      group: preserveGroup(e) || 'default',
       live: !isStaleEntry(e),
     });
   }
@@ -336,16 +419,34 @@ if (cmd === 'doctor') {
   console.log('');
   for (const r of rows) {
     console.log(`  [${r.live ? 'live ' : 'STALE'}] ${r.scope}`);
-    console.log(`           node: ${r.node}`);
-    console.log(`           path: ${r.path}`);
+    console.log(`           node:  ${r.node}`);
+    console.log(`           group: ${r.group}`);
+    console.log(`           path:  ${r.path}`);
   }
   const staleCount = rows.filter((r) => !r.live).length;
+
+  // Heuristic: if multiple entries reference the same Claude identity
+  // (same machine) but disagree on group, peers will see each other as
+  // disconnected — same incident pattern that cost ~24h of duplex outage
+  // at SYM.BOT (CMO=default vs COO=sym-bot-team, 2026-05-02). Surface as
+  // a warning so users can spot the mismatch before reaching for the
+  // troubleshooting section.
+  const groups = new Set(rows.map((r) => r.group));
+  const groupMismatch = rows.length > 1 && groups.size > 1;
+
   console.log('');
   if (staleCount > 0) {
     console.log(`${staleCount} stale entr${staleCount === 1 ? 'y' : 'ies'} — run \`sym-mesh-channel init\` to heal.`);
   } else {
     console.log('All entries are live.');
   }
+  if (groupMismatch) {
+    console.log('');
+    console.log(`⚠ Group mismatch across entries: ${Array.from(groups).join(', ')}.`);
+    console.log('  Nodes in different groups cannot discover each other on Bonjour.');
+    console.log('  If teammates expect to see each other, align the SYM_GROUP env var.');
+    console.log('  See README "Team mesh groups → Persisting your group across restarts".');
+  }
   process.exit(0);
 }
 
@@ -370,6 +471,11 @@ if (existingTopEntry && !force && !topEntryIsStale) {
 // Preserve the prior node name on rewrite so mesh identity doesn't drift.
 const topNodeName = preserveNodeName(existingTopEntry) || nodeName;
 
+// Resolve SYM_GROUP for the global entry — see resolveGroup() at top.
+// Heal-path default preserves; --force lets the user explicitly switch
+// groups (or back to default mesh) in one command.
+const topGroup = resolveGroup(existingTopEntry);
+
 // ── Build the entry ───────────────────────────────────────────────
 
 const entry = {
@@ -389,6 +495,9 @@ const entry = {
     SYM_RELAY_TOKEN: '',
   },
 };
+// SYM_GROUP only emitted when explicitly chosen — see project-mode comment
+// for the rationale. Omitted = node uses the global _sym._tcp default.
+if (topGroup) entry.env.SYM_GROUP = topGroup;
 
 claudeJson.mcpServers['claude-sym-mesh'] = entry;
 
@@ -407,7 +516,11 @@ for (const [projPath, proj] of Object.entries(projects)) {
   if (!projEntry) continue;
   if (!isStaleEntry(projEntry)) continue;
   const projNodeName = preserveNodeName(projEntry) || nodeName;
-  proj.mcpServers['claude-sym-mesh'] = {
+  // Preserve SYM_GROUP on stale-heal — same reason as preserveNodeName.
+  // The user explicitly chose this group at some prior install; healing a
+  // path issue must not silently revert their group membership.
+  const projGroupName = preserveGroup(projEntry);
+  const healedEntry = {
     command: 'node',
     args: [serverJsPath],
     env: {
@@ -416,7 +529,9 @@ for (const [projPath, proj] of Object.entries(projects)) {
       SYM_RELAY_TOKEN: projEntry.env && typeof projEntry.env.SYM_RELAY_TOKEN === 'string' ? projEntry.env.SYM_RELAY_TOKEN : '',
     },
   };
-  healedProjects.push({ path: projPath, node: projNodeName });
+  if (projGroupName) healedEntry.env.SYM_GROUP = projGroupName;
+  proj.mcpServers['claude-sym-mesh'] = healedEntry;
+  healedProjects.push({ path: projPath, node: projNodeName, group: projGroupName });
 }
 
 // ── Atomic write ──────────────────────────────────────────────────
@@ -459,7 +574,7 @@ const launchCmd = `claude --dangerously-load-development-channels server:claude-
 
 const healedLines = healedProjects.length
   ? '\n  Healed stale project-scoped entries (now pointing at fresh server.js):\n' +
-    healedProjects.map((p) => `    • ${p.path}  (node: ${p.node})`).join('\n') + '\n'
+    healedProjects.map((p) => `    • ${p.path}  (node: ${p.node}${p.group ? `, group: ${p.group}` : ''})`).join('\n') + '\n'
   : '';
 
 const nodeNameSuffix = topEntryIsStale ? ' (preserved from stale entry)' : '';
@@ -468,6 +583,7 @@ console.log(`
 ✓ sym-mesh-channel configured globally in ~/.claude.json
 
   Node name:     ${topNodeName}${nodeNameSuffix}
+  Mesh group:    ${topGroup || 'default (global _sym._tcp mesh)'}
   Server path:   ${serverJsPath}
   Backup:        ${backupPath}
 ${healedLines}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sym-bot/mesh-channel",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "MCP server — real-time agent-to-agent cognition for Claude Code remote teams via the SYM mesh.",
   "main": "server.js",
   "bin": {
@@ -22,7 +22,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "@sym-bot/sym": "^0.5.1"
+    "@sym-bot/sym": "^0.5.8"
   },
   "engines": {
     "node": ">=18"

package/server.js

@@ -241,14 +241,25 @@ function registerNodeHandlers(n) {
     const focus = entry.cmb?.fields?.focus?.text || entry.content || '';
     const mood = entry.cmb?.fields?.mood?.text || '';
     const moodSuffix = mood && mood !== 'neutral' ? ` (mood: ${mood})` : '';
-    // Store the rendered CMB body so the agent can sym_fetch it by [mNNN] ID,
-    // matching the contract stated in the MCP instructions and the behaviour
-    // of the raw-text `message` path. Without this, CAT7 CMBs (the primary
-    // traffic — sym_send / sym_observe) arrive as headlines with no
-    // retrievable body, degrading real-time duplex to headline-only.
-    const body = entry.content || focus;
+    // Store the rendered CMB body so the agent can sym_fetch it by [mNNN] ID.
+    // When the CMB carries an opaque payload alongside CAT7 fields, append a
+    // PAYLOAD section to the stored body so sym_fetch returns it intact;
+    // header gains a [+payload Nb] indicator so the receiver knows there's
+    // structured data beyond CAT7 and should sym_fetch to consume it.
+    const payload = entry.cmb?.payload;
+    const hasPayload = payload !== undefined && payload !== null;
+    let body = entry.content || focus;
+    let payloadSuffix = '';
+    if (hasPayload) {
+      const serialized = (() => {
+        try { return JSON.stringify(payload, null, 2); }
+        catch { return String(payload); }
+      })();
+      body = `${body}\n\n---PAYLOAD---\n${serialized}`;
+      payloadSuffix = ` [+payload ${serialized.length}b]`;
+    }
     const msgId = storeMessage(source, body);
-    pushChannel('cmb', `[${source}] ${focus}${moodSuffix} [${msgId}]`);
+    pushChannel('cmb', `[${source}] ${focus}${moodSuffix}${payloadSuffix} [${msgId}]`);
   });
 
   n.on('message', (from, content) => {
@@ -335,6 +346,14 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
               'Target peer: either the peer display name (e.g. "claude-research-win") or the full nodeId. ' +
               'Call sym_peers first if unsure which peers are connected. Omit to broadcast to all peers.',
           },
+          payload: {
+            description:
+              'Optional opaque payload riding alongside CAT7 fields. Use when carrying data beyond ' +
+              'CAT7 — e.g. an LLM request/response substrate protocol puts the prompt + request_id ' +
+              'in `payload` rather than smuggling JSON through `motivation` (which is reserved for ' +
+              'CAT7 semantics). Receivers see the payload via sym_fetch on the channel notification. ' +
+              'Any JSON-serializable value.',
+          },
         },
         required: ['focus'],
       },
@@ -362,6 +381,12 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
               arousal: { type: 'number' },
             },
           },
+          payload: {
+            description:
+              'Optional opaque payload riding alongside CAT7 fields. Use when broadcasting data ' +
+              'beyond CAT7 (e.g. llm-capability-advertise carrying served_capabilities). ' +
+              'Any JSON-serializable value.',
+          },
         },
         required: ['focus'],
       },
@@ -493,7 +518,10 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
         targetPeerId = matches[0].peerId;
       }
 
-      const entry = node.remember(fields, targetPeerId ? { to: targetPeerId } : {});
+      const sendOpts = {};
+      if (targetPeerId) sendOpts.to = targetPeerId;
+      if (args.payload !== undefined && args.payload !== null) sendOpts.payload = args.payload;
+      const entry = node.remember(fields, sendOpts);
       if (!entry) {
         return { content: [{ type: 'text', text: 'Duplicate — CMB already in memory, not re-broadcast.' }] };
       }
@@ -513,7 +541,9 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
         perspective: args.perspective || NODE_NAME,
         mood: args.mood || { text: 'neutral', valence: 0, arousal: 0 },
       };
-      const entry = node.remember(fields);
+      const observeOpts = {};
+      if (args.payload !== undefined && args.payload !== null) observeOpts.payload = args.payload;
+      const entry = node.remember(fields, observeOpts);
       return { content: [{ type: 'text', text: entry ? `Observed: ${entry.key}` : 'Duplicate — already in memory.' }] };
     }