feat(cli+broker): three-tier peer removal: disconnect, kick, ban

Broker (apps/broker/src/index.ts)
- Unified disconnect/kick handler uses close code 1000 for disconnect
  (CLI auto-reconnects) vs 4001 for kick (CLI exits, no reconnect).
- Ban now closes with code 4002.
- Hello handler: revoked members get a specific 'revoked' error with a
  'Contact the mesh owner to rejoin' message, then ws.close(4002).
  Previously banned users saw the generic 'unauthorized' error.
- list_bans handler returns { name, pubkey, revokedAt } for each
  revoked member.

CLI (apps/cli)
- ws-client: close codes 4001 and 4002 set .closed = true and stash
  .terminalClose so callers can surface a friendly message instead of
  the low-level 'ws terminal close' error. Revoked error in hello is
  also captured as a terminal close.
- withMesh catches terminalClose and prints:
  4001 → 'Kicked from this mesh. Run claudemesh to rejoin.'
  4002 → the broker's 'Contact the mesh owner to rejoin.' message
- kick.ts now exports runDisconnect + runKick with clear hints:
  'disconnect' → 'They will auto-reconnect within seconds.'
  'kick'       → 'They can rejoin anytime by running claudemesh.'
- cli.ts adds 'disconnect' dispatch; HELP updated.

Semantics:
  disconnect: session reset, no DB state, auto-reconnects
  kick      : session ends, no DB state, user must manually rejoin
  ban       : session ends + revokedAt set, cannot rejoin until unban

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

apps/cli/src/commands/connect.ts

@@ -75,6 +75,21 @@ export async function withMesh<T>(
     await client.connect();
     const result = await fn(client, mesh);
     return result;
+  } catch (e) {
+    // Terminal close from the broker (banned / kicked). Give the user
+    // a clear message instead of the low-level ws error.
+    if (client.terminalClose) {
+      const { code, reason } = client.terminalClose;
+      if (code === 4002) {
+        console.error(`\n  ✘ ${reason}\n`);
+      } else if (code === 4001) {
+        console.error(`\n  ✘ Kicked from this mesh. Run \`claudemesh\` to rejoin.\n`);
+      } else {
+        console.error(`\n  ✘ Broker closed connection: ${reason}\n`);
+      }
+      process.exit(1);
+    }
+    throw e;
   } finally {
     client.close();
   }

apps/cli/src/commands/kick.ts

@@ -1,9 +1,13 @@
 /**
- * `claudemesh kick` — disconnect peers from the mesh.
+ * `claudemesh disconnect` — soft disconnect (session reset, auto-reconnects).
+ * `claudemesh kick`       — hard kick (session ends, no auto-reconnect).
  *
- *   claudemesh kick <name>         kick one peer (can reconnect)
- *   claudemesh kick --stale 30m    kick idle peers (> 30 min no activity)
- *   claudemesh kick --all          kick everyone except yourself
+ *   claudemesh disconnect <peer>          # nudge, reconnects in seconds
+ *   claudemesh kick <peer>                # stop session, user runs claudemesh to rejoin
+ *   claudemesh kick --stale 30m           # kick peers idle > 30m
+ *   claudemesh kick --all                 # kick everyone except yourself
+ *
+ * Ban (permanent, revokes membership) is in ban.ts.
  */
 
 import { withMesh } from "./connect.js";
@@ -22,6 +26,44 @@ function parseStaleMs(input: string): number | null {
   return null;
 }
 
+function buildPayload(
+  kind: "disconnect" | "kick",
+  target: string | undefined,
+  opts: { stale?: string; all?: boolean },
+): Record<string, unknown> | { error: string } {
+  if (opts.all) return { type: kind, all: true };
+  if (opts.stale) {
+    const ms = parseStaleMs(opts.stale);
+    if (!ms) return { error: `Invalid stale duration: "${opts.stale}". Use e.g. 30m, 1h, 300s.` };
+    return { type: kind, stale: ms };
+  }
+  if (target) return { type: kind, target };
+  return { error: `Usage: claudemesh ${kind} <peer> | --stale 30m | --all` };
+}
+
+export async function runDisconnect(
+  target: string | undefined,
+  opts: { mesh?: string; stale?: string; all?: boolean } = {},
+): Promise<number> {
+  const config = readConfig();
+  const meshSlug = opts.mesh ?? config.meshes[0]?.slug;
+  if (!meshSlug) { render.err("No mesh joined."); return EXIT.NOT_FOUND; }
+
+  const built = buildPayload("disconnect", target, opts);
+  if ("error" in built) { render.err(String(built.error)); return EXIT.INVALID_ARGS; }
+
+  return await withMesh({ meshSlug }, async (client) => {
+    const result = await client.sendAndWait(built as Record<string, unknown>) as { affected?: string[]; kicked?: string[] };
+    const peers = result?.affected ?? result?.kicked ?? [];
+    if (peers.length === 0) render.info("No peers matched.");
+    else {
+      render.ok(`Disconnected ${peers.length} peer(s): ${peers.join(", ")}`);
+      render.hint("They will auto-reconnect within seconds. For a session-ending kick, use `claudemesh kick`.");
+    }
+    return EXIT.SUCCESS;
+  });
+}
+
 export async function runKick(
   target: string | undefined,
   opts: { mesh?: string; stale?: string; all?: boolean } = {},
@@ -30,29 +72,16 @@ export async function runKick(
   const meshSlug = opts.mesh ?? config.meshes[0]?.slug;
   if (!meshSlug) { render.err("No mesh joined."); return EXIT.NOT_FOUND; }
 
+  const built = buildPayload("kick", target, opts);
+  if ("error" in built) { render.err(String(built.error)); return EXIT.INVALID_ARGS; }
+
   return await withMesh({ meshSlug }, async (client) => {
-    let payload: Record<string, unknown>;
-
-    if (opts.all) {
-      payload = { type: "kick", all: true };
-    } else if (opts.stale) {
-      const ms = parseStaleMs(opts.stale);
-      if (!ms) { render.err(`Invalid stale duration: "${opts.stale}". Use e.g. 30m, 1h, 300s.`); return EXIT.INVALID_ARGS; }
-      payload = { type: "kick", stale: ms };
-    } else if (target) {
-      payload = { type: "kick", target };
-    } else {
-      render.err("Usage: claudemesh kick <peer> | --stale 30m | --all");
-      return EXIT.INVALID_ARGS;
-    }
-
-    const result = await client.sendAndWait(payload) as { kicked?: string[] };
-    const kicked = result?.kicked ?? [];
-
-    if (kicked.length === 0) {
-      render.info("No peers matched.");
-    } else {
-      render.ok(`Kicked ${kicked.length} peer(s): ${kicked.join(", ")}`);
+    const result = await client.sendAndWait(built as Record<string, unknown>) as { affected?: string[]; kicked?: string[] };
+    const peers = result?.affected ?? result?.kicked ?? [];
+    if (peers.length === 0) render.info("No peers matched.");
+    else {
+      render.ok(`Kicked ${peers.length} peer(s): ${peers.join(", ")}`);
+      render.hint("Their Claude Code session ended. They can rejoin anytime by running `claudemesh`.");
     }
     return EXIT.SUCCESS;
   });

apps/cli/src/entrypoints/cli.ts

@@ -30,9 +30,10 @@ Mesh
   claudemesh delete [slug]         delete a mesh (alias: rm)
   claudemesh rename <slug> <name>  rename a mesh
   claudemesh share [email]         share mesh (invite link / send email)
-  claudemesh kick <peer>           disconnect a peer (can reconnect)
-  claudemesh kick --stale 30m      disconnect idle peers (> duration)
-  claudemesh kick --all            disconnect everyone except you
+  claudemesh disconnect <peer>     soft disconnect (peer auto-reconnects)
+  claudemesh kick <peer>           end session (peer must manually rejoin)
+  claudemesh kick --stale 30m      kick peers idle > duration
+  claudemesh kick --all            kick everyone except yourself
   claudemesh ban <peer>            kick + permanently revoke (can't rejoin)
   claudemesh unban <peer>          lift a ban
   claudemesh bans                  list banned members
@@ -139,6 +140,7 @@ async function main(): Promise<void> {
     case "delete": case "rm": { const { deleteMesh } = await import("~/commands/delete-mesh.js"); process.exit(await deleteMesh(positionals[0] ?? "", { yes: !!flags.y || !!flags.yes })); break; }
     case "rename": { const { rename } = await import("~/commands/rename.js"); process.exit(await rename(positionals[0] ?? "", positionals[1] ?? "")); break; }
     case "share": case "invite": { const { invite } = await import("~/commands/invite.js"); process.exit(await invite(positionals[0], { mesh: flags.mesh as string, json: !!flags.json })); break; }
+    case "disconnect": { const { runDisconnect } = await import("~/commands/kick.js"); process.exit(await runDisconnect(positionals[0], { mesh: flags.mesh as string, stale: flags.stale as string, all: !!flags.all })); break; }
     case "kick": { const { runKick } = await import("~/commands/kick.js"); process.exit(await runKick(positionals[0], { mesh: flags.mesh as string, stale: flags.stale as string, all: !!flags.all })); break; }
     case "ban": { const { runBan } = await import("~/commands/ban.js"); process.exit(await runBan(positionals[0], { mesh: flags.mesh as string })); break; }
     case "unban": { const { runUnban } = await import("~/commands/ban.js"); process.exit(await runUnban(positionals[0], { mesh: flags.mesh as string })); break; }

apps/cli/src/services/broker/ws-client.ts

@@ -166,6 +166,8 @@ export class BrokerClient {
   private _serviceCatalog: Array<{ name: string; description: string; status: string; tools: Array<{ name: string; description: string; inputSchema: object }>; deployed_by: string }> = [];
   get serviceCatalog() { return this._serviceCatalog; }
   private closed = false;
+  /** Non-null when the broker closed us with a terminal code (4001/4002). */
+  public terminalClose: { code: number; reason: string } | null = null;
   private reconnectAttempt = 0;
   private helloTimer: NodeJS.Timeout | null = null;
   private reconnectTimer: NodeJS.Timeout | null = null;
@@ -321,10 +323,23 @@ export class BrokerClient {
         this.handleServerMessage(msg);
       };
 
-      const onClose = (): void => {
+      const onClose = (code?: number, reasonBuf?: Buffer): void => {
         if (this.helloTimer) clearTimeout(this.helloTimer);
         this.helloTimer = null;
         if (this.ws === ws) this.ws = null;
+        const reason = reasonBuf?.toString("utf-8") ?? "";
+        // Terminal close codes — broker told us to stay gone.
+        //   4001 = kicked (session ended, user must manually rejoin)
+        //   4002 = banned (member revoked, cannot rejoin until unbanned)
+        if (code === 4001 || code === 4002) {
+          this.closed = true;
+          this.setConnStatus("closed");
+          this.terminalClose = { code, reason };
+          if (this._status !== "open") {
+            reject(new Error(`ws terminal close ${code}: ${reason || "session ended"}`));
+          }
+          return;
+        }
         if (this._status !== "open" && this._status !== "reconnecting") {
           reject(new Error("ws closed before hello_ack"));
         }
@@ -2158,6 +2173,11 @@ export class BrokerClient {
     }
     if (msg.type === "error") {
       this.debug(`broker error: ${msg.code} ${msg.message}`);
+      // Terminal errors from hello — broker will close us next. Capture
+      // so the caller (launch/peers/etc.) can surface a friendly message.
+      if (msg.code === "revoked") {
+        this.terminalClose = { code: 4002, reason: String(msg.message ?? "revoked") };
+      }
       const id = msg.id ? String(msg.id) : null;
       let handledByPendingSend = false;
       if (id) {