@sym-bot/mesh-channel 0.3.13 → 0.3.15

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sym-mesh-channel",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "description": "Real-time Claude-to-Claude mesh. Agent-to-agent cognitive signals over Bonjour LAN or WebSocket relay.",
   "author": {
     "name": "Hongwei Xu",

package/.mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@sym-bot/mesh-channel@0.3.10"
+        "@sym-bot/mesh-channel@0.3.14"
       ],
       "env": {
         "SYM_RELAY_URL": "${user_config.relay_url}",

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.3.15
+
+### Fixed
+
+- **`start` now finds `claude` on Windows.** The launch used `spawnSync('claude', …)` with no shell, which does an exact-filename lookup that ignores Windows `PATHEXT` — so `start` failed with `ENOENT` even when `claude` ran fine in the shell (there it resolves a `.cmd`/`.ps1` shim or `.exe`, never bare `claude`). The launch now routes through a shell on Windows so `PATHEXT` resolution applies; whitespace args are quoted since `shell: true` forwards them unquoted. The POSIX launch path is unchanged.
+- **`start --name` no longer silently reverts identity on a stale entry.** `start` auto-injected `--force` only on a *live* entry mismatch, but `npx` rotates its cached `server.js` path on every version resolve, so the persisted entry is routinely stale yet still holds the node's name/group. On a re-run, `start` saw no live entry, pushed no `--force`, and `init`'s preserve-over-request precedence dropped the requested `--name` — reverting the node's identity to the stale name. `start` now reconciles against the persisted entry whether or not it's stale and forces the rewrite when an explicit `--name`/`--group` differs. The group is preserved when no `--group` is passed.
+
+## 0.3.14
+
+### Added
+
+- **`sym-mesh-channel start` — one command to a live mesh session.** Configures the MCP server if needed, then launches Claude Code with the real-time Channels flag already on, so users never type `--dangerously-load-development-channels …` or have to choose between the `plugin:` and `server:` handle. `start --project --name <node> --group <team>` stands up a named mesh agent; `start --print` is a dry run; everything after `--` is forwarded to `claude`. Co-resident sessions don't collide (server.js auto-suffixes a live-identity clash since 0.3.10), so `start` in several terminals just works.
+
+### Fixed
+
+- **CLI subcommand dispatch via the published bin.** The `bin` entrypoint (`server.js`) only routed `init` to the installer, so `npx @sym-bot/mesh-channel doctor` silently fell through and started the MCP server instead. Now `init`, `doctor`, and `start` all route to the installer/launcher.
+- **`init --force` with an explicit `SYM_NODE_NAME` now relabels the entry** instead of always preserving the prior name (symmetric with how `--group` already behaves). A routine reinstall with no explicit name still preserves identity.
+
 ## 0.3.13
 
 ### Changed

package/README.md

@@ -66,37 +66,39 @@ They're **not alternatives** — the channel is built *on* sym and speaks the sa
 
 ## Quick start
 
-Install the published plugin — in Claude Code:
+**One command — it configures the mesh and launches Claude Code with real-time push already on:**
 
 ```
-/plugin marketplace add anthropics/claude-plugins-community
-/plugin install sym-mesh-channel@claude-community
+npx @sym-bot/mesh-channel@latest start
 ```
 
-That gives you all **11 MCP tools — no flag, no npm, nothing else to add** — and **one install covers every Claude Code session on the machine**: open as many as you like (one per repo, or one planning while another codes); each gets its own mesh identity and picks up the mesh on resume. The first command is a one-time marketplace registration.
+Run it in any repo, in as many terminals as you like — the sessions discover each other over loopback (or the same wifi) and **think together in real time**. No flag to remember, no `plugin:` vs `server:` to choose — `start` wires the channel for you. (First run configures the MCP server; after that it just launches. Co-resident sessions don't collide — each becomes its own peer.)
 
-Discoverable in Claude Code too — `/plugin` → **Discover** → search "mesh".
-
-Want the always-latest build straight from the source repo? Add it as its own marketplace instead:
+Stand up a persistent **named** agent, or join a team room:
 
 ```
-/plugin marketplace add sym-bot/sym-mesh-channel
-/plugin install sym-mesh-channel@sym-mesh-channel
+npx @sym-bot/mesh-channel@latest start --name cto --group my-team
 ```
 
-This tracks `main`, so it can be a few versions ahead of the community listing (whose pinned build lags until the next directory sync). **Whichever marketplace you install from, the channel flag below must use that same `@<marketplace>` handle** — `@claude-community` for the directory install above, `@sym-mesh-channel` for this source-repo install. Mismatching them is the #1 cause of `plugin … not installed` when launching with the channel flag.
+(`start --print` shows the exact `claude …` command without launching; anything after `--` is passed straight to `claude`, e.g. `… start -- --resume`.)
+
+### Prefer the Claude Code plugin UI?
 
-### Real-time push (the `<channel>` experience)
+Install the plugin and you get the 11 MCP tools immediately:
+
+```
+/plugin install sym-mesh-channel@claude-community
+```
 
-The tools above are pull-based. For a peer's message to **land in Claude's context mid-turn, with no tool call** — the "Claude thinks with the mesh" experience the screenshots show — Claude Code has to load this plugin's *channel*, which is currently gated behind a flag while it awaits Anthropic's approved-channels allowlist:
+For real-time push on this path, launch with the channel flag (the handle must match where you installed from):
 
 ```
 claude --dangerously-load-development-channels plugin:sym-mesh-channel@claude-community
 ```
 
-(If you installed from the source-repo marketplace instead, use `plugin:sym-mesh-channel@sym-mesh-channel` — the `@<marketplace>` must match wherever you installed from.)
+Want the latest build before the community directory syncs? Add SYM.BOT's own catalog instead — `/plugin marketplace add sym-bot/marketplace`, then `/plugin install sym-mesh-channel@sym-bot` (and launch with `plugin:sym-mesh-channel@sym-bot`).
 
-The flag becomes unnecessary once the channel is allowlisted — tracked in [anthropics/claude-plugins-official#1512](https://github.com/anthropics/claude-plugins-official/issues/1512).
+> **The dev flag is temporary** — an Anthropic-side gate while the channel awaits the approved-channels allowlist ([anthropics/claude-plugins-official#1512](https://github.com/anthropics/claude-plugins-official/issues/1512)). `start` passes it under the hood today; once the channel is allowlisted it disappears. Curious when to use the npm/server install directly (named agents, repo-committed team config, the `sym` CLI)? See [Advanced](#advanced-named-agents-teams--the-cli).
 
 ## What you get
 
@@ -234,7 +236,9 @@ The plugin composes two open specs:
 
 ## Advanced: per-project node identity
 
-By default every Claude Code session on a machine shares one mesh identity (set globally in `~/.claude.json`). If you run several Claude Code sessions in parallel from distinct project directories and want each to appear as its own peer on the mesh — e.g. a "research" session and a "strategy" session on the same laptop — install per-project instead:
+*(npm / MCP-server install only — plugin sessions already get a distinct peer identity each.)*
+
+With the global npm install, every Claude Code session on the machine shares one mesh identity (set in `~/.claude.json`). To give each project directory its own stable peer name instead — e.g. a "research" session and a "strategy" session on the same laptop — install per-project:
 
 ```bash
 cd path/to/your/project
@@ -345,7 +349,7 @@ Some corporate networks block mDNS multicast entirely — try a hotspot or home
 
 The 11 tools work without any flag. The real-time `<channel>` **push** is separate: Claude Code only delivers channel notifications for channels on its **approved-channels allowlist**, and sym-mesh-channel isn't on it yet — so push requires the development-channels flag matching your install path:
 
-- plugin install: `--dangerously-load-development-channels plugin:sym-mesh-channel@claude-community` (or `@sym-mesh-channel` if you installed from the source-repo marketplace — the handle must match your install source)
+- plugin install: `--dangerously-load-development-channels plugin:sym-mesh-channel@claude-community` (or `@sym-bot` if you installed from the source-repo marketplace — the handle must match your install source)
 - npm install: `--dangerously-load-development-channels server:claude-sym-mesh`
 
 This is an Anthropic-side gate, not a bug here — once the channel is allowlisted the flag is no longer needed. Tracked in [anthropics/claude-plugins-official#1512](https://github.com/anthropics/claude-plugins-official/issues/1512).
@@ -358,15 +362,25 @@ Your shell profile (`~/.zshrc`, `~/.bashrc`) exports `SYM_RELAY_URL`. Claude Cod
 
 Don't. Each session should have a distinct `SYM_NODE_NAME`. The SymNode acquires an exclusive lockfile on its identity (`~/.sym/nodes/<name>/lock.pid`) and refuses to start a second process with the same name. If you see `EIDENTITYLOCK`, kill the other process or pick a different name. For multiple parallel sessions with their own identities, use the per-project install above.
 
-## Other install paths
+## Advanced: named agents, teams & the CLI
 
-### Via npm (server install)
+Everything above uses the plugin — all most users need. Install the engine as an npm package / MCP server instead **only** when you want one of these:
+
+- **A persistent, *named* agent.** The plugin auto-names each session (`claude-myrepo-3f9a`); the server install lets you pin `SYM_NODE_NAME=cto` so the node always appears under the same name in `sym_peers`, mesh memory, and CMB lineage — a durable agent identity, not an anonymous session.
+- **Team config committed to a repo.** Config lives in a project `.mcp.json`, so you can commit `SYM_GROUP=backend-team` (plus relay URL/token) into the repo — anyone who opens it in Claude Code auto-joins the team room with zero per-person setup.
+- **The `sym` CLI and non-Claude agents.** This also installs [`@sym-bot/sym`](https://github.com/sym-bot/sym), giving you `sym ask` / `sym groups` in your terminal and an engine that other agents, scripts, and languages can share.
 
 ```bash
 npm install -g @sym-bot/mesh-channel
 ```
 
-Installs the engine globally and exposes it as an MCP server (`server:claude-sym-mesh`). Use this if you prefer npm for install/update management, or want `@sym-bot/sym` available outside the plugin surface. (For real-time push on this path, see [Troubleshooting](#channel-notifications-never-arrive-even-though-peers-are-connected).)
+This registers a raw MCP server keyed `claude-sym-mesh`. Because it's a server (not a plugin), its real-time channel handle is **`server:claude-sym-mesh`** — so launch with:
+
+```bash
+claude --dangerously-load-development-channels server:claude-sym-mesh
+```
+
+Pin a fixed per-session identity with [per-project node identity](#advanced-per-project-node-identity); set relay credentials in the env block per [cross-network setup](#cross-network-setup-own-hosted-relay).
 
 ## References
 

package/bin/install.js

@@ -55,8 +55,8 @@ const cmd = args.find((a) => !a.startsWith('--')) || 'init';
 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] [--group <name>]\n       sym-mesh-channel doctor\n`);
+if (cmd !== 'init' && cmd !== 'doctor' && cmd !== 'start') {
+  process.stderr.write(`Unknown command: ${cmd}\nUsage: sym-mesh-channel start [--project] [--name <node>] [--group <name>] [-- <claude args>]\n       sym-mesh-channel init [--project] [--force] [--group <name>]\n       sym-mesh-channel doctor\n`);
   process.exit(1);
 }
 
@@ -111,6 +111,115 @@ function preserveGroup(entry) {
   return g || null;
 }
 
+// ── start: one command to a live mesh session ─────────────────────
+// `sym-mesh-channel start` configures the MCP server (only if needed)
+// and then launches Claude Code with the real-time Channels flag
+// already on — so the user never types `--dangerously-load-development-
+// channels …` or has to choose between the plugin: and server: handle.
+// The npx / MCP-server install path always exposes the channel as a raw
+// server, so the handle is deterministically `server:claude-sym-mesh`.
+//
+//   sym-mesh-channel start                       # this dir, real-time push on
+//   sym-mesh-channel start --project --name cto --group my-team
+//   sym-mesh-channel start --print               # show the command, don't launch
+//   sym-mesh-channel start -- --resume           # pass args through to claude
+//
+// Co-resident sessions sharing one config don't collide: server.js
+// auto-suffixes a live-identity clash (since 0.3.10), so each session
+// becomes its own peer.
+if (cmd === 'start') {
+  const { spawnSync } = require('child_process');
+
+  const nameArgIdx = args.indexOf('--name');
+  const nameArg = nameArgIdx !== -1 ? args[nameArgIdx + 1] : null;
+  const printOnly = args.includes('--print') || args.includes('--dry-run');
+
+  // Everything after `--` is forwarded verbatim to `claude`.
+  const dashDash = args.indexOf('--');
+  const passthrough = dashDash !== -1 ? args.slice(dashDash + 1) : [];
+
+  const launchDir = process.cwd();
+
+  const handle = 'server:claude-sym-mesh';
+  const claudeArgs = ['--dangerously-load-development-channels', handle, ...passthrough];
+
+  // --print is a pure dry-run: show the launch command, change nothing.
+  if (printOnly) {
+    console.log(`claude ${claudeArgs.join(' ')}`);
+    process.exit(0);
+  }
+
+  // Is the scope Claude Code will actually read already configured with a
+  // LIVE entry?  --project → <cwd>/.mcp.json ; otherwise → ~/.claude.json
+  // Reconcile identity against the persisted entry whether or not its
+  // server.js path is stale. npx rotates the cached server.js path on every
+  // version resolve (…/_npx/<hash>/…), so the entry is routinely stale yet
+  // still carries the node's name/group. Comparing only against a *live*
+  // entry let an explicit --name lose to the stale name on the heal path:
+  // start saw no live entry, pushed no --force, and init's non-force
+  // precedence (preserve-over-request) kept the old identity.
+  function rawEntryInScope() {
+    try {
+      const p = isProject
+        ? path.join(launchDir, '.mcp.json')
+        : path.join(os.homedir(), '.claude.json');
+      if (!fs.existsSync(p)) return null;
+      const j = JSON.parse(fs.readFileSync(p, 'utf8'));
+      return (j && j.mcpServers && j.mcpServers['claude-sym-mesh']) || null;
+    } catch { return null; }
+  }
+
+  const existing = rawEntryInScope();
+  const stale = existing ? isStaleEntry(existing) : false;
+  const wantName = nameArg || null;
+  const wantGroup = groupArg || null;
+  const mismatch = !!existing && (
+    (wantName && preserveNodeName(existing) !== wantName) ||
+    (wantGroup && (preserveGroup(existing) || 'default') !== wantGroup)
+  );
+
+  // Configure when there's nothing persisted yet, the persisted server.js
+  // path is stale (heal), an explicit --name/--group differs, or --force.
+  // Otherwise launch straight away — `start` stays cheap to run every
+  // session.
+  if (!existing || stale || mismatch || force) {
+    const initArgs = ['init'];
+    if (isProject) initArgs.push('--project');
+    if (groupArg) initArgs.push('--group', groupArg);
+    // --force makes init honor the explicit --name/--group over the
+    // persisted value. Required on the rename path AND on stale-heal with
+    // an explicit --name, where init would otherwise preserve the old name
+    // and silently drop the request. Force alone never clobbers an
+    // unspecified group: resolveGroup() still preserves when no --group.
+    if (existing && (mismatch || force)) initArgs.push('--force');
+    const childEnv = Object.assign({}, process.env);
+    if (nameArg) childEnv.SYM_NODE_NAME = nameArg;
+    const r = spawnSync(process.execPath, [__filename, ...initArgs], {
+      stdio: 'inherit', env: childEnv, cwd: launchDir,
+    });
+    if (r.status !== 0) process.exit(r.status == null ? 1 : r.status);
+  }
+
+  console.log(`\n▶ Launching Claude Code on the SYM mesh — real-time push on.\n  (channel: ${handle}; the dev flag is temporary until Anthropic allowlists it)\n`);
+  // On Windows the `claude` CLI is a `.cmd`/`.ps1` shim (npm) or `.exe`
+  // (native installer). Node's spawn does an exact-filename lookup that
+  // ignores PATHEXT, so bare `spawnSync('claude', …)` returns ENOENT even
+  // when `claude` runs fine in the user's shell. Route through a shell on
+  // Windows so PATHEXT resolution kicks in; quote args that contain spaces
+  // since shell:true forwards the args unquoted.
+  const isWindows = process.platform === 'win32';
+  const spawnArgs = isWindows
+    ? claudeArgs.map((a) => (/\s/.test(a) ? `"${a}"` : a))
+    : claudeArgs;
+  const run = spawnSync('claude', spawnArgs, { stdio: 'inherit', cwd: launchDir, shell: isWindows });
+  if (run.error && run.error.code === 'ENOENT') {
+    process.stderr.write('ERROR: `claude` was not found on your PATH.\n');
+    process.stderr.write('Install Claude Code (https://claude.com/code), make sure `claude` runs in your terminal, then re-run `sym-mesh-channel start`.\n');
+    process.exit(127);
+  }
+  process.exit(run.status == null ? 0 : run.status);
+}
+
 // --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.
@@ -219,9 +328,12 @@ if (useProjectMode) {
     process.exit(2);
   }
 
-  // Preserve the prior node name on rewrite so mesh identity doesn't drift
-  // back to the hostname default on every reinstall.
-  const projectNodeName = preserveNodeName(existingProjectEntry) || nodeName;
+  // --force + an explicit SYM_NODE_NAME deliberately relabels this entry
+  // (symmetric with resolveGroup). Otherwise preserve the prior name so the
+  // mesh identity doesn't drift back to the hostname default on a reinstall.
+  const projectNodeName = (force && process.env.SYM_NODE_NAME)
+    ? process.env.SYM_NODE_NAME
+    : (preserveNodeName(existingProjectEntry) || nodeName);
 
   // Group resolution priority — see resolveGroup() at top of file.
   // Summary: --force + explicit flag/env wins; otherwise preserve, then
@@ -469,7 +581,9 @@ if (existingTopEntry && !force && !topEntryIsStale) {
 }
 
 // Preserve the prior node name on rewrite so mesh identity doesn't drift.
-const topNodeName = preserveNodeName(existingTopEntry) || nodeName;
+const topNodeName = (force && process.env.SYM_NODE_NAME)
+  ? process.env.SYM_NODE_NAME
+  : (preserveNodeName(existingTopEntry) || nodeName);
 
 // Resolve SYM_GROUP for the global entry — see resolveGroup() at top.
 // Heal-path default preserves; --force lets the user explicitly switch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sym-bot/mesh-channel",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "MCP server — real-time agent-to-agent cognition for Claude Code remote teams via the SYM mesh.",
   "main": "server.js",
   "bin": {

package/server.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 'use strict';
 
-// Subcommand dispatch: `sym-mesh-channel init` runs the installer.
-if (process.argv[2] === 'init') {
+// Subcommand dispatch: CLI subcommands run the installer/launcher, not the
+// MCP server. (When Claude Code spawns the server there is no subcommand, so
+// argv[2] is undefined and this falls through to the MCP server below.)
+if (['init', 'doctor', 'start'].includes(process.argv[2])) {
   require('./bin/install.js');
   return;
 }

package/.claude-plugin/marketplace.json

@@ -1,46 +0,0 @@
-{
-  "name": "sym-mesh-channel",
-  "owner": {
-    "name": "SYM.BOT",
-    "email": "info@sym.bot"
-  },
-  "metadata": {
-    "description": "Real-time communication and collaboration among Claude Code sessions — agent-to-agent cognitive signals over Bonjour LAN or WebSocket relay, on the Mesh Memory Protocol (MMP).",
-    "version": "0.3.11"
-  },
-  "plugins": [
-    {
-      "name": "sym-mesh-channel",
-      "source": "./",
-      "description": "Real-time communication and collaboration among Claude Code sessions. Turns Claude Code into a peer node on the SYM mesh — two or more sessions discover each other via Bonjour (LAN) or a WebSocket relay (cross-network) and exchange structured cognitive signals as channel notifications. Each peer has its own Ed25519 identity, SVAF content gating, and local memory. Built on the Mesh Memory Protocol (MMP), an open peer-to-peer protocol for multi-agent collective intelligence.",
-      "version": "0.3.11",
-      "author": {
-        "name": "Hongwei Xu",
-        "email": "hongwei@sym.bot"
-      },
-      "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"
-      ],
-      "category": "agents",
-      "tags": [
-        "mesh",
-        "cognitive",
-        "channel",
-        "mcp",
-        "multi-agent"
-      ]
-    }
-  ]
-}