@kvsm/blether 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,84 @@
+# Blether
+
+Agent-to-agent communication for distributed teams of human developers.
+
+Each developer's coding agent can message the agents of their teammates, on other machines, to give a heads-up before a change, ask the owner of some code instead of guessing, or say that something they were waiting on has landed. Messages are asynchronous: they wait in a mailbox until the receiving agent reads them. They're signed by the sending device and end-to-end encrypted, so the relay that carries them never sees what was said.
+
+> **Status:** early development. Expect breaking changes, and read [Safety](https://github.com/kvsm/blether#safety) before letting agents act on what they receive.
+
+This package contains:
+
+- **`blether`**: the CLI developers use to manage their identity, teams, agents and Approval Policy. Agents can't change any of those.
+- **`blether-bridge`**: a local MCP server that gives an agent its Blether tools.
+- **The Claude Code plugin**: the bridge, new-mail notices, and the `/blether:connect` and `/blether:setup` skills.
+
+Teams also need a relay, which holds each agent's mailbox. It's published as the Docker image [`ghcr.io/kvsm/blether-relay`](https://github.com/kvsm/blether/blob/main/docs/self-hosting.md).
+
+## Quickstart
+
+You need Node 24, and an invite link from a teammate whose team already has a relay. To start a team instead, you need a relay: see [Run a relay](https://github.com/kvsm/blether#2-run-a-relay).
+
+```sh
+npm install -g @kvsm/blether
+blether claude install                 # adds the plugin to Claude Code (the CLI and VS Code)
+```
+
+Then open Claude Code in a project, with `claude` in the terminal or in VS Code, and run `/blether:setup`. Claude walks you through the rest, running the commands for you:
+
+1. **Your identity:** your name, as teammates will see it. Once per developer.
+2. **Your team:** joins it with your invite, or creates a new one.
+3. **This project's agent:** the named mailbox your sessions here act as. Teammates' agents message it by name, so pick one that says what it works on, such as `web-app` or `payments-api`. You can give it roles, such as `frontend` or `reviewer`, so teammates can message every agent covering an area at once.
+4. **Connecting:** the session connects to Blether, and is told whenever a message arrives.
+
+Claude can now message your teammates' agents. In later sessions, run `/blether:connect` when you want to work with your team. Sessions you don't connect leave Blether out entirely.
+
+By default Claude asks you before it sends any message, and before it acts on any request it receives. `blether policy` shows your Approval Policy, and `blether help` lists every command.
+
+### By hand
+
+To set up without the skill, or for an agent other than Claude Code, run the steps yourself:
+
+```sh
+blether init --name <name>             # your identity, once per developer
+blether join <invite>                  # prints "Joined <team>."
+blether role list <team>               # the team's roles, such as frontend or reviewer
+blether role add <team> <role>         # add one if what your agent does isn't listed
+blether agent create <team> <agent name> --role <role>   # an agent you own; --role is optional, and can repeat
+
+cd <project>                           # each project an agent works in
+blether use <team> <agent name>        # sessions started here act as <agent name>
+```
+
+In Claude Code, start a new session in the project and run `/blether:connect`. For other agents, see [Other agents](#other-agents) below. To start a team or run a relay, see [Getting started](https://github.com/kvsm/blether#getting-started).
+
+## Other agents
+
+Any agent that speaks MCP can use the bridge. Add it to the agent's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "blether": { "command": "blether-bridge" }
+  }
+}
+```
+
+The bridge acts as the agent named in the project's `.blether/session.json`, which `blether use` writes. For guidance on when and how to message teammates, give the agent the skill at `$(npm root -g)/@kvsm/blether/plugin/skills/blether/SKILL.md`.
+
+## Updating
+
+```sh
+npm install -g @kvsm/blether@latest
+blether --version                      # shows the version now installed
+blether claude install                 # if you use Claude Code: updates the plugin to match
+```
+
+Then restart your agent sessions. Your identity, teams and projects are left as they are. See [Updating](https://github.com/kvsm/blether#updating) for the details.
+
+## Documentation
+
+The [README on GitHub](https://github.com/kvsm/blether#readme) covers how Blether works, what agents can do, the safety controls (Approval Policy, sending limits, the secret check and escalations), managing devices and teams, and configuration. [Hosting a relay](https://github.com/kvsm/blether/blob/main/docs/self-hosting.md) covers running one for your team.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kvsm/blether",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Agent-to-agent communication for distributed teams of human developers: the blether CLI, the bridge (an MCP server), and the Claude Code plugin.",
   "keywords": [
     "agents",
@@ -10,6 +10,8 @@
     "messaging"
   ],
   "license": "MIT",
+  "homepage": "https://github.com/kvsm/blether#readme",
+  "bugs": "https://github.com/kvsm/blether/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kvsm/blether.git"
@@ -29,8 +31,8 @@
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",
     "esbuild": "^0.28.2",
-    "@blether/bridge": "0.0.0",
-    "@blether/relay": "0.0.0"
+    "@blether/bridge": "0.2.1",
+    "@blether/relay": "0.2.1"
   },
   "publishConfig": {
     "access": "public"

package/plugin/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "blether",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "displayName": "Blether",
-  "description": "Message your teammates' coding agents through Blether: the bridge, push delivery, and skills for when and how to reach out.",
+  "description": "Message your teammates' coding agents through Blether: the bridge, new-mail notices, and skills for when and how to reach out.",
   "author": {
     "name": "Kev Smith"
   },
@@ -14,14 +14,9 @@
       "command": "node",
       "args": ["${CLAUDE_PLUGIN_ROOT}/dist/bridge.js"],
       "env": {
-        "BLETHER_PROJECT_DIR": "${CLAUDE_PROJECT_DIR}"
+        "BLETHER_PROJECT_DIR": "${CLAUDE_PROJECT_DIR}",
+        "BLETHER_CONNECT": "manual"
       }
     }
-  },
-  "channels": [
-    {
-      "server": "blether",
-      "displayName": "Blether"
-    }
-  ]
+  }
 }

package/plugin/dist/bridge.js

@@ -36959,6 +36959,9 @@ var DeviceGrant = external_exports.object({
   teams: external_exports.array(external_exports.object({ name: TeamName, id: external_exports.string(), relayUrl: external_exports.url() }))
 });
 
+// ../protocol/dist/version.js
+var BLETHER_VERSION = "0.2.1";
+
 // ../protocol/dist/wire.js
 var AudienceHint = external_exports.object({
   audience: external_exports.union([external_exports.object({ kind: external_exports.literal("agent") }), Audience]),
@@ -37573,9 +37576,79 @@ var SentLog = class {
   }
 };
 
+// ../bridge/dist/inbox-file.js
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync5, renameSync, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join5 } from "node:path";
+var InboxState = external_exports.object({
+  /** Changes each time a bridge starts, so a watcher can tell a restart from new mail. */
+  session: external_exports.string(),
+  /** Messages that have arrived since this bridge started, counting up. */
+  arrivals: external_exports.number().int().min(0),
+  unread: external_exports.number().int().min(0),
+  /** Who the waiting messages are from, oldest first, each once. */
+  from: external_exports.array(external_exports.string()),
+  /** The latest arrival's sender, if any has arrived this session. */
+  lastFrom: external_exports.string().optional(),
+  updatedAt: external_exports.string(),
+  /** Set when the bridge disconnected this session from the relay. */
+  closed: external_exports.boolean().optional()
+});
+function inboxPath(home, team, agent) {
+  if (!/^[A-Za-z0-9_-]+$/.test(team + agent)) {
+    throw new Error("Bad team or agent name.");
+  }
+  return join5(home, "inbox", `${team}.${agent}.json`);
+}
+var InboxFile = class {
+  path;
+  now;
+  /** Identifies this connection, so a watch can tell when it has ended. */
+  session = randomUUID2();
+  arrivals = 0;
+  lastFrom;
+  closed = false;
+  constructor(path2, now = () => /* @__PURE__ */ new Date()) {
+    this.path = path2;
+    this.now = now;
+  }
+  /** Records an arrival (from `from`), then the mailbox as it now stands. */
+  arrived(from, unread, senders) {
+    this.arrivals++;
+    if (from)
+      this.lastFrom = from;
+    this.write(unread, senders);
+  }
+  /** Records that this session has disconnected, so its watch stops. */
+  close() {
+    this.write(0, [], true);
+    this.closed = true;
+  }
+  /** Records the mailbox as it now stands, after a read or at start-up. */
+  write(unread, senders, closed = false) {
+    if (this.closed)
+      return;
+    const state = {
+      session: this.session,
+      arrivals: this.arrivals,
+      unread,
+      from: senders,
+      ...this.lastFrom ? { lastFrom: this.lastFrom } : {},
+      updatedAt: this.now().toISOString(),
+      ...closed ? { closed } : {}
+    };
+    mkdirSync5(join5(this.path, ".."), { recursive: true });
+    const temp = `${this.path}.${process.pid}.tmp`;
+    writeFileSync5(temp, `${JSON.stringify(state)}
+`);
+    renameSync(temp, this.path);
+  }
+};
+
 // ../bridge/dist/session-file.js
-import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "node:fs";
-import { dirname, join as join5, resolve } from "node:path";
+import { existsSync as existsSync6, mkdirSync as mkdirSync6, readFileSync as readFileSync6, writeFileSync as writeFileSync6 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname, join as join6, resolve } from "node:path";
 var SessionFileContents = external_exports.object({
   team: external_exports.string().min(1),
   agent: AgentName
@@ -37584,16 +37657,21 @@ var DIR = ".blether";
 var FILE = "session.json";
 var SessionFileError = class extends Error {
 };
+function isBletherHome(dir, bletherHome) {
+  const same = (a2, b2) => process.platform === "win32" ? resolve(a2).toLowerCase() === resolve(b2).toLowerCase() : resolve(a2) === resolve(b2);
+  const candidate = join6(dir, DIR);
+  return same(candidate, bletherHome) || same(candidate, join6(homedir2(), DIR));
+}
 function findSessionFile(start, bletherHome) {
   let dir = resolve(start);
   for (; ; ) {
-    const candidate = join5(dir, DIR);
-    const path2 = join5(candidate, FILE);
-    if (resolve(candidate) !== resolve(bletherHome) && existsSync5(path2)) {
+    const candidate = join6(dir, DIR);
+    const path2 = join6(candidate, FILE);
+    if (!isBletherHome(dir, bletherHome) && existsSync6(path2)) {
       return { path: path2, contents: readSessionFile(path2) };
     }
     const parent = dirname(dir);
-    if (existsSync5(join5(dir, ".git")) || parent === dir)
+    if (existsSync6(join6(dir, ".git")) || parent === dir)
       return void 0;
     dir = parent;
   }
@@ -37601,19 +37679,19 @@ function findSessionFile(start, bletherHome) {
 function readSessionFile(path2) {
   let raw;
   try {
-    raw = JSON.parse(readFileSync5(path2, "utf8"));
+    raw = JSON.parse(readFileSync6(path2, "utf8"));
   } catch (error62) {
-    throw new SessionFileError(`${path2} isn't valid JSON (${error62.message}). Write it again with \`blether use <team> <agent>\`.`);
+    throw new SessionFileError(`${path2} isn't valid JSON (${error62.message}). Write it again with \`blether use <team> <agent name>\`.`);
   }
   const parsed = SessionFileContents.safeParse(raw);
   if (!parsed.success) {
-    throw new SessionFileError(`${path2} doesn't name a team and agent. Write it again with \`blether use <team> <agent>\`.`);
+    throw new SessionFileError(`${path2} doesn't name a team and agent. Write it again with \`blether use <team> <agent name>\`.`);
   }
   return parsed.data;
 }
 
 // ../bridge/dist/relay-connection.js
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID3 } from "node:crypto";
 
 // ../../node_modules/.pnpm/ws@8.22.0/node_modules/ws/wrapper.mjs
 var import_stream = __toESM(require_stream(), 1);
@@ -37676,6 +37754,7 @@ var RelayConnection = class _RelayConnection {
    */
   identity;
   arrivalListeners = /* @__PURE__ */ new Set();
+  readListeners = /* @__PURE__ */ new Set();
   constructor(socket, credentials, scope, witness, readMessages) {
     this.socket = socket;
     this.credentials = credentials;
@@ -37774,7 +37853,7 @@ var RelayConnection = class _RelayConnection {
     if (devices.length === 0) {
       throw new RelayError("untrusted-reply", `Couldn't find the devices of ${to}'s developer to encrypt for.`);
     }
-    const id = randomUUID2();
+    const id = randomUUID3();
     const envelope = sealMessage({
       id,
       team: scope.team,
@@ -37825,7 +37904,7 @@ var RelayConnection = class _RelayConnection {
   }
   /** The `limit` messages this agent sent most recently, newest first. */
   listSent(limit = 20) {
-    const requestId = randomUUID2();
+    const requestId = randomUUID3();
     return this.request(this.listings, requestId, {
       type: "list-sent",
       requestId,
@@ -37841,6 +37920,11 @@ var RelayConnection = class _RelayConnection {
     const from = this.unread.map((item) => item.kind === "lost" ? "lost-message notices" : item.from);
     return [...new Set(from)];
   }
+  /** Calls `listener` after each mailbox read. Returns a function that unsubscribes. */
+  onRead(listener) {
+    this.readListeners.add(listener);
+    return () => this.readListeners.delete(listener);
+  }
   /** Calls `listener` whenever a new message arrives. Returns a function that unsubscribes. */
   onArrival(listener) {
     this.arrivalListeners.add(listener);
@@ -37866,6 +37950,8 @@ var RelayConnection = class _RelayConnection {
     if (read.length > 0 && this.socket.readyState === import_websocket.default.OPEN) {
       this.write({ type: "read", ids: read });
     }
+    for (const listener of this.readListeners)
+      listener();
     return items;
   }
   /** A message read earlier in this session, by id. */
@@ -37887,7 +37973,7 @@ var RelayConnection = class _RelayConnection {
   }
   /** Starts a team whose log is `log`, returning it as the relay stored it. */
   async createTeam(log) {
-    const requestId = randomUUID2();
+    const requestId = randomUUID3();
     const reply = await this.request(this.teamRequests, requestId, {
       type: "create-team",
       requestId,
@@ -37897,7 +37983,7 @@ var RelayConnection = class _RelayConnection {
   }
   /** The names of team `id`'s agents that have a session connected. */
   getPresence(id) {
-    const requestId = randomUUID2();
+    const requestId = randomUUID3();
     return this.request(this.presenceRequests, requestId, {
       type: "get-presence",
       requestId,
@@ -37921,7 +38007,7 @@ var RelayConnection = class _RelayConnection {
   }
   /** Fetches team `id`'s log and verifies it. */
   async getTeam(id) {
-    const requestId = randomUUID2();
+    const requestId = randomUUID3();
     const reply = await this.request(this.teamRequests, requestId, {
       type: "get-team",
       requestId,
@@ -37931,7 +38017,7 @@ var RelayConnection = class _RelayConnection {
   }
   /** Appends `entry` to team `id`'s log, returning the verified result. */
   async appendTeam(id, entry) {
-    const requestId = randomUUID2();
+    const requestId = randomUUID3();
     const reply = await this.request(this.teamRequests, requestId, {
       type: "append-team",
       requestId,
@@ -38197,7 +38283,7 @@ function take(map2, key) {
 }
 
 // ../bridge/dist/server.js
-import { randomUUID as randomUUID3 } from "node:crypto";
+import { randomUUID as randomUUID4 } from "node:crypto";
 
 // ../../node_modules/.pnpm/zod@4.6.5/node_modules/zod/v3/helpers/util.js
 var util;
@@ -51027,7 +51113,7 @@ var CLAUDE_CHANNEL = "claude/channel";
 var CLAUDE_CHANNEL_NOTIFICATION = "notifications/claude/channel";
 function createSetupProblemServer(problem, { takeOver } = {}) {
   const explanation = `Blether isn't working in this session: ${problem}`;
-  const server2 = new McpServer({ name: "blether", version: "0.0.0" }, {
+  const server2 = new McpServer({ name: "blether", version: BLETHER_VERSION }, {
     instructions: `${explanation} Blether's messaging tools are unavailable until this is fixed. If your developer asks about Blether, or you need to message another agent, tell them this and suggest the fix.`,
     // Declared up front so a session that takes its agent over can still
     // receive channel notices.
@@ -51057,9 +51143,59 @@ function createSetupProblemServer(problem, { takeOver } = {}) {
   }
   return server2;
 }
+function createDormantServer(connect2) {
+  const server2 = new McpServer({ name: "blether", version: BLETHER_VERSION }, { capabilities: { experimental: { [CLAUDE_CHANNEL]: {} } } });
+  const offerConnect = () => {
+    const connectTool = server2.registerTool("connect", {
+      title: "Connect to Blether",
+      description: "Connects this session to Blether, so you can message the agents of other developers on your team. Call it ONLY when your developer runs /blether:connect or /blether:setup. Never call it otherwise, even if they ask you to connect: tell them to run /blether:connect instead."
+    }, async () => {
+      let connected;
+      try {
+        connected = await connect2(server2);
+      } catch (error62) {
+        return {
+          ...text(`Couldn't connect to Blether: ${error62.message}`),
+          isError: true
+        };
+      }
+      connectTool.remove();
+      const disconnectTool = server2.registerTool("disconnect", {
+        title: "Disconnect from Blether",
+        description: "Disconnects this session from Blether. Call it ONLY when your developer runs /blether:disconnect. Never call it otherwise, even if they ask you to disconnect: tell them to run /blether:disconnect instead."
+      }, async () => {
+        const result = await connected.disconnect();
+        disconnectTool.remove();
+        offerConnect();
+        return text(result);
+      });
+      return text(connected.result);
+    });
+  };
+  offerConnect();
+  return server2;
+}
+function removableTools(server2, install) {
+  const added = [];
+  const register = server2.registerTool.bind(server2);
+  server2.registerTool = ((...args) => {
+    const tool = register(...args);
+    added.push(tool);
+    return tool;
+  });
+  try {
+    install();
+  } finally {
+    delete server2.registerTool;
+  }
+  return () => {
+    for (const tool of added.splice(0))
+      tool.remove();
+  };
+}
 function createBridgeServer(relay, { policy = STRICTEST_POLICY, escalations, now = () => /* @__PURE__ */ new Date(), scanSecrets = scanForSecrets, sentLog, server: existing } = {}) {
   const pendingAtStart = escalations?.pending().length ?? 0;
-  const server2 = existing ?? new McpServer({ name: "blether", version: "0.0.0" }, {
+  const server2 = existing ?? new McpServer({ name: "blether", version: BLETHER_VERSION }, {
     instructions: [
       INSTRUCTIONS,
       ...escalations ? [
@@ -51144,7 +51280,7 @@ function createBridgeServer(relay, { policy = STRICTEST_POLICY, escalations, now
       if (approval !== "approved") {
         return respond(`Not sent: ${approval}`, true);
       }
-      const fanout = randomUUID3();
+      const fanout = randomUUID4();
       const sendOne = async (recipient) => {
         const receipt = await relay.send(recipient, body, {
           audience,
@@ -51459,13 +51595,15 @@ var SetupProblem = class extends Error {
 };
 var REFUSAL_FIXES = {
   "agent-in-use": (agent) => `Only one session can act as ${agent} at a time. If the other one is still in use, close it (it may be in another terminal, or on another of your devices) or choose a different agent for this project with \`blether use\`. If this session should be ${agent} instead, use take_over_agent.`,
-  "agent-owned-by-another": (agent, team) => `${agent} is another developer's agent. Use one of yours (\`blether agent list ${team}\`) or create one with \`blether agent create ${team} <name>\`, then restart this session.`,
+  "agent-owned-by-another": (agent, team) => `${agent} is another developer's agent. Use one of yours (\`blether agent list ${team}\`) or create one with \`blether agent create ${team} <agent name>\`, then restart this session.`,
   "not-a-member": () => "Ask a teammate for an invite and run `blether join <invite>`, then restart this session.",
   "unknown-team": (_agent, team) => `The relay doesn't know ${team}; it may have been reset. Check the relay is the right one, or create the team again with \`blether team create\`.`,
   "authentication-failed": () => "This device's identity didn't verify. Check `blether whoami`; if it's damaged, set this device up again.",
   "identity-conflict": () => "The relay holds a different history for your identity than this device does. Don't add devices from two places at once; ask for help before going further."
 };
 async function startBridge(env = process.env, log = (line) => console.error(line)) {
+  if (env.BLETHER_CONNECT === "manual")
+    return startDormant(env, log);
   try {
     const { server: server2, connection } = await connect(env, log);
     return {
@@ -51500,7 +51638,65 @@ async function startBridge(env = process.env, log = (line) => console.error(line
     };
   }
 }
-async function connect(env, log) {
+function startDormant(env, log) {
+  let connected;
+  const disconnect = async () => {
+    const opened = connected;
+    connected = void 0;
+    if (!opened)
+      return;
+    opened.removeTools();
+    try {
+      opened.inbox.close();
+    } catch {
+    }
+    await opened.connection.close();
+  };
+  const server2 = createDormantServer(async (server3) => {
+    let opened;
+    try {
+      opened = await connect(env, log, server3);
+    } catch (error62) {
+      if (error62 instanceof SetupProblem) {
+        throw new Error(error62.message, { cause: error62 });
+      }
+      throw error62;
+    }
+    connected = opened;
+    log(`blether bridge connected as ${opened.agent}`);
+    return {
+      result: connectedGuidance(opened),
+      disconnect: async () => {
+        await disconnect();
+        log("blether bridge disconnected");
+        return "Disconnected from Blether. Your watch stops by itself, and Blether's tools are gone until your developer runs /blether:connect again.";
+      }
+    };
+  });
+  return {
+    server: server2,
+    close: async () => {
+      await server2.close();
+      await disconnect();
+    }
+  };
+}
+function connectedGuidance({ agent, team, inbox, pendingEscalations }) {
+  const path2 = inbox.path.split("\\").join("/");
+  const watch = `blether watch --inbox "${path2}" --session ${inbox.session}`;
+  return [
+    `Connected to Blether: you are ${agent} in team ${team.name}.`,
+    INSTRUCTIONS,
+    ...pendingEscalations > 0 ? [
+      `${pendingEscalations} escalation(s) from earlier sessions are waiting for your developer: call list_escalations and raise them with your developer.`
+    ] : [],
+    "",
+    "Now:",
+    "1. Call read_mailbox.",
+    `2. Start a watch, so you hear about new mail between prompts: use the Monitor tool (load it with ToolSearch first if it's deferred) with the command: ${watch} \u2014 the description "Blether mail for ${agent}", and timeout_ms 1800000. Each line it prints means new mail: call read_mailbox. When the watch expires, start it again. If it stops by itself (this session disconnected, or another session took the agent over), don't.`
+  ].join("\n");
+}
+async function connect(env, log, into) {
   const home = env.BLETHER_HOME ?? defaultBletherHome();
   let session;
   try {
@@ -51512,11 +51708,11 @@ async function connect(env, log) {
   }
   const agentName = env.BLETHER_AGENT ?? session?.contents.agent;
   if (agentName === void 0) {
-    throw new SetupProblem("No agent is chosen for this project. Run `blether use <team> <agent>` in the project (`blether agent list <team>` shows the agents), then restart this session.");
+    throw new SetupProblem("No agent is chosen for this project. Run `blether use <team> <agent name>` in the project (`blether agent list <team>` shows the agents), then restart this session.");
   }
   const agent = AgentName.safeParse(agentName);
   if (!agent.success) {
-    throw new SetupProblem(`BLETHER_AGENT is set to "${agentName}", which isn't an agent name (lowercase letters, digits and hyphens). Fix it in this agent's MCP config, or remove it and run \`blether use <team> <agent>\` in the project.`);
+    throw new SetupProblem(`BLETHER_AGENT is set to "${agentName}", which isn't an agent name (lowercase letters, digits and hyphens). Fix it in this agent's MCP config, or remove it and run \`blether use <team> <agent name>\` in the project.`);
   }
   if (session)
     log(`blether bridge using ${session.path}`);
@@ -51532,7 +51728,7 @@ async function connect(env, log) {
   }
   const teamName = env.BLETHER_TEAM ?? session?.contents.team;
   if (!teamName) {
-    throw new SetupProblem("No team is chosen for this project. Run `blether use <team> <agent>` in the project (`blether team list` shows your teams), then restart this session.");
+    throw new SetupProblem("No team is chosen for this project. Run `blether use <team> <agent name>` in the project (`blether team list` shows your teams), then restart this session.");
   }
   let team;
   try {
@@ -51547,13 +51743,13 @@ async function connect(env, log) {
 Messages are end-to-end encrypted; the relay sees only who messaged whom, and when.`);
   const found = { store, credentials, team, agent: agent.data, log };
   try {
-    return await open2(found, false);
+    return await open2(found, into !== void 0, into);
   } catch (error62) {
     if (!(error62 instanceof RelayError)) {
       throw new SetupProblem(`Couldn't connect to the relay at ${team.relayUrl}: ${error62.message}. Is it running? Start it, then restart this session.`);
     }
     const fix = REFUSAL_FIXES[error62.code]?.(agent.data, team.name);
-    throw new SetupProblem(`The relay refused this session (${error62.code}): ${error62.message}${fix ? ` ${fix}` : ""}`, error62.code === "agent-in-use" ? async (server2) => (await open2(found, true, server2)).connection : void 0);
+    throw new SetupProblem(`The relay refused this session (${error62.code}): ${error62.message}${fix ? ` ${fix}` : ""}`, error62.code === "agent-in-use" && !into ? async (server2) => (await open2(found, true, server2)).connection : void 0);
   }
 }
 async function open2({ store, credentials, team, agent, log }, takeover, server2) {
@@ -51567,13 +51763,43 @@ async function open2({ store, credentials, team, agent, log }, takeover, server2
   if (relay.identity && relay.identity.length > credentials.identity.length) {
     store.saveIdentity(relay.identity);
   }
-  const bridge = createBridgeServer(relay, {
+  const inbox = new InboxFile(inboxPath(store.home, team.id, agent));
+  keepInboxFile(relay, inbox);
+  const escalations = new EscalationStore(store.home, team.id, agent);
+  const options = {
     policy: new PolicyStore(store.home).load(),
-    escalations: new EscalationStore(store.home, team.id, agent),
-    sentLog: new SentLog(store.home, team.id, agent),
-    ...server2 ? { server: server2 } : {}
-  });
-  return { server: bridge, connection: relay };
+    escalations,
+    sentLog: new SentLog(store.home, team.id, agent)
+  };
+  let bridge;
+  let removeTools = () => {
+  };
+  if (server2) {
+    bridge = server2;
+    removeTools = removableTools(server2, () => createBridgeServer(relay, { ...options, server: server2 }));
+  } else {
+    bridge = createBridgeServer(relay, options);
+  }
+  return {
+    server: bridge,
+    connection: relay,
+    agent,
+    team,
+    inbox,
+    removeTools,
+    pendingEscalations: escalations.pending().length
+  };
+}
+function keepInboxFile(relay, inbox) {
+  const attempt = (write) => {
+    try {
+      write();
+    } catch {
+    }
+  };
+  relay.onArrival((item) => attempt(() => inbox.arrived(item.kind === "lost" ? void 0 : item.from, relay.unreadCount, relay.unreadFrom())));
+  relay.onRead(() => attempt(() => inbox.write(relay.unreadCount, relay.unreadFrom())));
+  void relay.settled().then(() => attempt(() => inbox.write(relay.unreadCount, relay.unreadFrom())));
 }
 
 // ../bridge/dist/bin.js

package/plugin/dist/cli.js

@@ -27617,6 +27617,9 @@ function parseDeviceGrant(text) {
   }
 }
 
+// ../protocol/dist/version.js
+var BLETHER_VERSION = "0.2.1";
+
 // ../protocol/dist/wire.js
 var AudienceHint = external_exports.object({
   audience: external_exports.union([external_exports.object({ kind: external_exports.literal("agent") }), Audience]),
@@ -28007,6 +28010,7 @@ var RelayConnection = class _RelayConnection {
    */
   identity;
   arrivalListeners = /* @__PURE__ */ new Set();
+  readListeners = /* @__PURE__ */ new Set();
   constructor(socket, credentials, scope, witness, readMessages) {
     this.socket = socket;
     this.credentials = credentials;
@@ -28172,6 +28176,11 @@ var RelayConnection = class _RelayConnection {
     const from = this.unread.map((item) => item.kind === "lost" ? "lost-message notices" : item.from);
     return [...new Set(from)];
   }
+  /** Calls `listener` after each mailbox read. Returns a function that unsubscribes. */
+  onRead(listener) {
+    this.readListeners.add(listener);
+    return () => this.readListeners.delete(listener);
+  }
   /** Calls `listener` whenever a new message arrives. Returns a function that unsubscribes. */
   onArrival(listener) {
     this.arrivalListeners.add(listener);
@@ -28197,6 +28206,8 @@ var RelayConnection = class _RelayConnection {
     if (read.length > 0 && this.socket.readyState === import_websocket.default.OPEN) {
       this.write({ type: "read", ids: read });
     }
+    for (const listener of this.readListeners)
+      listener();
     return items;
   }
   /** A message read earlier in this session, by id. */
@@ -28695,6 +28706,7 @@ var PolicyStore = class {
 
 // ../bridge/dist/session-file.js
 import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
 import { dirname, join as join4, resolve } from "node:path";
 var SessionFileContents = external_exports.object({
   team: external_exports.string().min(1),
@@ -28703,7 +28715,17 @@ var SessionFileContents = external_exports.object({
 var DIR = ".blether";
 var FILE = "session.json";
 var GITIGNORE = "# Written by `blether use`: this developer's own agent for the project.\n*\n";
-function writeSessionFile(projectDir, contents) {
+var SessionFileError = class extends Error {
+};
+function isBletherHome(dir, bletherHome) {
+  const same = (a2, b2) => process.platform === "win32" ? resolve(a2).toLowerCase() === resolve(b2).toLowerCase() : resolve(a2) === resolve(b2);
+  const candidate = join4(dir, DIR);
+  return same(candidate, bletherHome) || same(candidate, join4(homedir2(), DIR));
+}
+function writeSessionFile(projectDir, contents, bletherHome) {
+  if (isBletherHome(projectDir, bletherHome)) {
+    throw new SessionFileError(`${resolve(projectDir)} is your home directory, where Blether keeps your identity, not a project. Run "blether use" from the project's root, or give it --dir <project>.`);
+  }
   const dir = join4(projectDir, DIR);
   mkdirSync4(dir, { recursive: true });
   const ignore = join4(dir, ".gitignore");
@@ -28715,9 +28737,71 @@ function writeSessionFile(projectDir, contents) {
   return path;
 }
 
+// ../bridge/dist/inbox-file.js
+import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync5, renameSync, writeFileSync as writeFileSync5 } from "node:fs";
+var InboxState = external_exports.object({
+  /** Changes each time a bridge starts, so a watcher can tell a restart from new mail. */
+  session: external_exports.string(),
+  /** Messages that have arrived since this bridge started, counting up. */
+  arrivals: external_exports.number().int().min(0),
+  unread: external_exports.number().int().min(0),
+  /** Who the waiting messages are from, oldest first, each once. */
+  from: external_exports.array(external_exports.string()),
+  /** The latest arrival's sender, if any has arrived this session. */
+  lastFrom: external_exports.string().optional(),
+  updatedAt: external_exports.string(),
+  /** Set when the bridge disconnected this session from the relay. */
+  closed: external_exports.boolean().optional()
+});
+function readInboxState(path) {
+  if (!existsSync5(path))
+    return void 0;
+  try {
+    return InboxState.parse(JSON.parse(readFileSync5(path, "utf8")));
+  } catch {
+    return void 0;
+  }
+}
+function unreadSummary(state) {
+  if (!state || state.unread === 0)
+    return void 0;
+  return `\u{1F4EC} ${state.unread} unread Blether message${state.unread === 1 ? "" : "s"} (from ${state.from.join(", ")}). Call read_mailbox to read them.`;
+}
+
+// ../bridge/dist/watch.js
+function watchInbox(path, session, emit, end, { intervalMs = 1e3 } = {}) {
+  let arrivals;
+  let timer;
+  let stopped = false;
+  const stop = () => {
+    stopped = true;
+    clearInterval(timer);
+  };
+  const check2 = () => {
+    const state = readInboxState(path);
+    if (!state)
+      return;
+    if (state.session !== session || state.closed) {
+      stop();
+      end(state.session === session ? "disconnected" : "taken-over");
+      return;
+    }
+    const summary = unreadSummary(state);
+    const arrived = arrivals !== void 0 && state.arrivals > arrivals;
+    if (summary && (arrivals === void 0 || arrived)) {
+      emit(arrived && state.lastFrom ? `New Blether message from ${state.lastFrom}. ${summary}` : summary);
+    }
+    arrivals = state.arrivals;
+  };
+  check2();
+  if (!stopped)
+    timer = setInterval(check2, intervalMs);
+  return stop;
+}
+
 // ../bridge/dist/claude-install.js
 import { spawn } from "node:child_process";
-import { existsSync as existsSync5 } from "node:fs";
+import { existsSync as existsSync6 } from "node:fs";
 import { dirname as dirname2, join as join5, resolve as resolve2 } from "node:path";
 import { fileURLToPath } from "node:url";
 var PLUGIN_ID = "blether@blether";
@@ -28737,7 +28821,7 @@ var runClaude = (args) => new Promise((resolvePromise, reject) => {
 function packageRoot(from = dirname2(fileURLToPath(import.meta.url))) {
   let dir = resolve2(from);
   for (; ; ) {
-    if (existsSync5(join5(dir, ".claude-plugin", "marketplace.json")))
+    if (existsSync6(join5(dir, ".claude-plugin", "marketplace.json")))
       return dir;
     const parent = dirname2(dir);
     if (parent === dir)
@@ -28793,14 +28877,20 @@ Commands:
   device list                        List your identity's devices
   device revoke <fingerprint>        Revoke a lost or stolen device, from another of yours
   role add <team> <role>             Add a role to the team's agreed list
-  agent create <team> <name> [--role <r>]...
+  role list <team>                   List the team's roles
+  agent create <team> <agent name> [--role <r>]...
                                      Create an agent you own, with roles from the team's list
-  agent roles <team> <name> [--role <r>]...
+  agent roles <team> <agent name> [--role <r>]...
                                      Replace the roles of one of your agents
   agent list <team>                  Show the team's agents and who is online
-  agent delete <team> <name>         Delete one of your agents (or any, as Team Admin)
-  use <team> <agent> [--dir <path>]  Make sessions started in this project (or <path>) act as <agent>
+  agent delete <team> <agent name>
+                                     Delete one of your agents (or any, as Team Admin)
+  use <team> <agent name> [--dir <path>]
+                                     Make sessions started in this project (or <path>) act as the agent
   claude install                     Install (or update) the Blether plugin in Claude Code
+  watch --inbox <path> --session <id>
+                                     Print a line whenever a connected session's agent gets mail
+                                     (the bridge gives its agent this command when it connects)
   escalations                        List messages your agents are holding for your decision
   status                             One line for your Claude Code status line: escalations waiting
   policy                             Show your Approval Policy on this device
@@ -28810,6 +28900,7 @@ Commands:
                                      outgoing: ask | ask-others | free
                                      incoming: ask | ask-impactful | free
                                      limits: most messages an agent sends in the window
+  --version                          Show which version of Blether is installed
 
 Set BLETHER_HOME to keep Blether's files somewhere other than ~/.blether.`;
 var CliError = class extends Error {
@@ -28881,6 +28972,8 @@ ${USAGE}`);
       const [sub, ...args] = rest;
       if (sub === "add")
         return roleAdd(args, ctx);
+      if (sub === "list")
+        return roleList(args, ctx);
       throw new CliError(`Unknown role command: ${sub ?? "(none)"}
 
 ${USAGE}`);
@@ -28917,6 +29010,8 @@ ${USAGE}`);
     }
     case "use":
       return use(rest, ctx);
+    case "watch":
+      return watch(rest, ctx);
     case "claude": {
       const [sub] = rest;
       if (sub === "install")
@@ -28937,6 +29032,11 @@ ${USAGE}`);
     case "-h":
       ctx.io.out(USAGE);
       return command === void 0 ? 1 : 0;
+    case "version":
+    case "--version":
+    case "-v":
+      ctx.io.out(BLETHER_VERSION);
+      return 0;
     default:
       throw new CliError(`Unknown command: ${command}
 
@@ -28950,7 +29050,7 @@ function init(args, { store, io }) {
   });
   const name = DeveloperName.safeParse(values.name);
   if (!name.success) {
-    throw new CliError('Give your name, as teammates will see it: blether init --name "Kev"');
+    throw new CliError("Give your name, as teammates will see it: blether init --name <name>");
   }
   if (store.exists()) {
     throw new CliError(`There is already a Blether identity in ${store.home}. Run \`blether whoami\` to see it.`);
@@ -29329,6 +29429,19 @@ async function roleAdd(args, ctx) {
   ctx.io.out(`Added the ${role} role to ${record2.name}.`);
   return 0;
 }
+async function roleList(args, ctx) {
+  const record2 = loadTeam(ctx.teams, args[0]);
+  const credentials = loadCredentials(ctx.store);
+  const { team } = await withRelay(ctx, record2.relayUrl, credentials, (relay) => relay.getTeam(record2.id));
+  if (team.roles.length === 0) {
+    ctx.io.out(`${record2.name} has no roles yet. Add one with: blether role add ${record2.name} <role>`);
+    return 0;
+  }
+  ctx.io.out(`Roles in ${record2.name}:`);
+  for (const role of team.roles)
+    ctx.io.out(`  ${role}`);
+  return 0;
+}
 async function agentCreate(args, ctx) {
   const { values, positionals } = parseArgs({
     args,
@@ -29336,7 +29449,7 @@ async function agentCreate(args, ctx) {
     options: { role: { type: "string", multiple: true } }
   });
   const record2 = loadTeam(ctx.teams, positionals[0]);
-  const name = parseName(AgentName, positionals[1], "Usage: blether agent create <team> <name> [--role <role>]...");
+  const name = parseName(AgentName, positionals[1], "Usage: blether agent create <team> <agent name> [--role <role>]...");
   const roles = values.role ?? [];
   const credentials = loadCredentials(ctx.store);
   await withRelay(ctx, record2.relayUrl, credentials, async (relay) => {
@@ -29358,7 +29471,7 @@ async function agentRoles(args, ctx) {
     options: { role: { type: "string", multiple: true } }
   });
   const record2 = loadTeam(ctx.teams, positionals[0]);
-  const name = parseName(AgentName, positionals[1], "Usage: blether agent roles <team> <name> [--role <role>]...");
+  const name = parseName(AgentName, positionals[1], "Usage: blether agent roles <team> <agent name> [--role <role>]...");
   const roles = values.role ?? [];
   const credentials = loadCredentials(ctx.store);
   const me2 = verifyIdentityLog(credentials.identity).id;
@@ -29411,7 +29524,7 @@ async function teamRemove(args, ctx) {
 }
 async function agentDelete(args, ctx) {
   const record2 = loadTeam(ctx.teams, args[0]);
-  const name = parseName(AgentName, args[1], "Usage: blether agent delete <team> <name>");
+  const name = parseName(AgentName, args[1], "Usage: blether agent delete <team> <agent name>");
   const credentials = loadCredentials(ctx.store);
   const me2 = verifyIdentityLog(credentials.identity).id;
   await withRelay(ctx, record2.relayUrl, credentials, async (relay) => {
@@ -29427,6 +29540,27 @@ async function agentDelete(args, ctx) {
   ctx.io.out(`Deleted agent ${name} from ${record2.name}. Unread messages to it are lost, and their senders will be told. The name can be used again.`);
   return 0;
 }
+async function watch(args, ctx) {
+  const { values } = parseArgs({
+    args,
+    options: { inbox: { type: "string" }, session: { type: "string" } }
+  });
+  if (!values.inbox || !values.session) {
+    throw new CliError("Usage: blether watch --inbox <path> --session <id>");
+  }
+  const ended = await new Promise((resolve3) => {
+    const stop = watchInbox(values.inbox, values.session, ctx.io.out, (why) => resolve3(why === "taken-over" ? "Blether watch stopped: another session took over this agent." : "Blether watch stopped: this session disconnected from Blether."));
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+      process.once(signal, () => {
+        stop();
+        resolve3("");
+      });
+    }
+  });
+  if (ended)
+    ctx.io.out(ended);
+  return 0;
+}
 async function claudeInstall(ctx) {
   const root = "packageRoot" in ctx ? ctx.packageRoot : packageRoot();
   if (!root) {
@@ -29439,7 +29573,6 @@ async function claudeInstall(ctx) {
     throw new CliError(missing ? "Couldn't run `claude`. Install Claude Code, or check it's on your PATH." : error62.message);
   }
   ctx.io.out("Start a new Claude Code session to use it, and run /blether:setup in each project.");
-  ctx.io.out(`For push delivery, start sessions with: claude --dangerously-load-development-channels plugin:${PLUGIN_ID}`);
   return 0;
 }
 async function use(args, ctx) {
@@ -29448,7 +29581,7 @@ async function use(args, ctx) {
     allowPositionals: true,
     options: { dir: { type: "string" } }
   });
-  const usage = "Usage: blether use <team> <agent> [--dir <path>]";
+  const usage = "Usage: blether use <team> <agent name> [--dir <path>]";
   if (positionals.length === 0)
     throw new CliError(usage);
   const record2 = loadTeam(ctx.teams, positionals[0]);
@@ -29463,10 +29596,14 @@ async function use(args, ctx) {
   if (agent.owner !== me2) {
     throw new CliError(`${name} belongs to another developer. Use one of yours (blether agent list ${record2.name}), or create one.`);
   }
-  const path = writeSessionFile(values.dir ?? ctx.cwd ?? process.cwd(), {
-    team: record2.name,
-    agent: name
-  });
+  let path;
+  try {
+    path = writeSessionFile(values.dir ?? ctx.cwd ?? process.cwd(), { team: record2.name, agent: name }, ctx.store.home);
+  } catch (error62) {
+    if (error62 instanceof SessionFileError)
+      throw new CliError(error62.message);
+    throw error62;
+  }
   ctx.io.out(`Sessions started in this project will act as ${name} in ${record2.name}.`);
   ctx.io.out(`Wrote ${path}; it's ignored by git, since the agent is yours. Restart any session already running here.`);
   return 0;
@@ -29479,15 +29616,15 @@ async function agentList(args, ctx) {
     online: await relay.getPresence(record2.id)
   }));
   if (team.agents.length === 0) {
-    ctx.io.out(`${record2.name} has no agents yet. Create one with: blether agent create ${record2.name} <name>`);
-    return 0;
-  }
-  ctx.io.out(`Agents in ${record2.name}:`);
-  for (const agent of team.agents) {
-    const owner = identities.get(agent.owner)?.name ?? "(unknown)";
-    const roles = agent.roles.length > 0 ? agent.roles.join(", ") : "no roles";
-    const presence = online.includes(agent.name) ? "online" : "offline";
-    ctx.io.out(`  ${agent.name}  ${owner}, ${roles}, ${presence}`);
+    ctx.io.out(`${record2.name} has no agents yet. Create one with: blether agent create ${record2.name} <agent name>`);
+  } else {
+    ctx.io.out(`Agents in ${record2.name}:`);
+    for (const agent of team.agents) {
+      const owner = identities.get(agent.owner)?.name ?? "(unknown)";
+      const roles = agent.roles.length > 0 ? agent.roles.join(", ") : "no roles";
+      const presence = online.includes(agent.name) ? "online" : "offline";
+      ctx.io.out(`  ${agent.name}  ${owner}, ${roles}, ${presence}`);
+    }
   }
   if (team.roles.length > 0) {
     ctx.io.out(`Roles: ${team.roles.join(", ")}`);
@@ -29560,7 +29697,7 @@ async function join6(args, ctx) {
   });
   ctx.teams.save(record2);
   ctx.io.out(`Joined ${record2.name}.`);
-  ctx.io.out(`Create an agent with: blether agent create ${record2.name} <name>, then run blether use ${record2.name} <name> in your project.`);
+  ctx.io.out(`Create an agent with: blether agent create ${record2.name} <agent name>, then run blether use ${record2.name} <agent name> in your project.`);
   return 0;
 }
 function now(ctx) {

package/plugin/skills/blether/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: blether
-description: Message teammates' agents through Blether. Use before a change that affects code or interfaces another developer owns, when you need an answer only another developer's agent has, when your work blocks or unblocks someone, or when a Blether message arrives that needs a reply.
+description: Message teammates' agents through Blether, in a session the developer has connected with /blether:connect. Once connected, use before a change that affects code or interfaces another developer owns, when you need an answer only another developer's agent has, when your work blocks or unblocks someone, or when a Blether message arrives that needs a reply.
 ---
 
 # Working with your team through Blether
 
 Blether connects you to the agents of the other developers on your team. Each agent works for its own developer, in its own project. The bridge's tools (`list_agents`, `send_message`, `read_mailbox`, `sent_messages`) do the carrying, and each tool result says how to handle what it returns. This skill is about **when** to reach out and **how to write** so the other agent can act without coming back to you.
 
+Blether is used only in sessions the developer connects (`/blether:connect`). If the bridge's messaging tools aren't available, this session isn't connected: carry on without Blether, don't connect on your own, and don't bring it up.
+
 ## When to send
 
 - **Heads-up before you change something others depend on**: an API shape, a shared schema, a config key, a library version, a file layout. Send it before you commit, saying what changes and when, so their agent can adapt or object.

package/plugin/skills/connect/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: connect
+description: Connect this session to Blether, so it can message teammates' agents and hear about new mail.
+disable-model-invocation: true
+---
+
+# Connect this session to Blether
+
+The developer wants this session to use Blether. Until now the bridge has stayed out of it.
+
+1. Check whether another session is using the agent. Connecting takes the agent over, and the other session is disconnected without warning.
+   - Read `.blether/session.json` in the project root for the team and agent. If there isn't one, skip this check: the `connect` tool says what's missing.
+   - Run `blether agent list <team>` (the plugin puts `blether` on your Bash `PATH`). If the agent shows as `online`, another session is using it, perhaps in another terminal or on another device. Tell the developer, and go on only if they say to take it over.
+2. Call the bridge's `connect` tool (`mcp__plugin_blether_blether__connect`; load it with ToolSearch first if it's deferred).
+3. If it fails, tell the developer what it says. If no agent is chosen for this project, offer `/blether:setup`.
+4. If it connects, do what its result says: read the mailbox, then start the watch with the Monitor tool, exactly as given.
+5. Tell the developer in two or three lines: which agent this session is, what's waiting in the mailbox, and that you'll hear about new mail while connected.

package/plugin/skills/disconnect/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: disconnect
+description: Disconnect this session from Blether, so it stops messaging teammates' agents and hearing about new mail.
+disable-model-invocation: true
+---
+
+# Disconnect this session from Blether
+
+Call the bridge's `disconnect` tool (`mcp__plugin_blether_blether__disconnect`; load it with ToolSearch first if it's deferred). The watch stops by itself. Tell the developer in one line that the session is disconnected, and that `/blether:connect` connects it again.

package/plugin/skills/setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup
-description: Set up Blether for this project - identity, team, agent, push delivery and status line.
+description: Set up Blether for this project - identity, team, agent and status line - and connect this session.
 disable-model-invocation: true
 ---
 
@@ -31,23 +31,32 @@ Done when `team list` shows the team.
 
 ## 3. Agent for this project
 
-Run `agent list <team>` and ask which of **their** agents this project should act as, or what to call a new one. Agents are named for what they work on (`web`, `api`, `docs`), lowercase with hyphens. To create one, run `agent create <team> <name>`, adding `--role <role>` for roles the team already lists.
+First read `.blether/session.json` in the project root, if it exists: it names the team and agent the project already acts as. If so, tell them, and ask whether to keep it. Keeping it: go on to step 4, without running `use`.
 
-Then run `use <team> <agent>` in the project root. It writes `.blether/session.json`, which git ignores.
+Otherwise, run `agent list <team>` and ask which of **their** agents this project should act as, or what to call a new one. Teammates' agents message it by name, so suggest one that says what it works on (such as `web-app` or `payments-api`), lowercase with hyphens.
 
-Done when `use` reports the agent for this project.
+For a new agent, run `role list <team>` and ask which roles describe what it does. Roles let teammates message every agent covering an area at once, and are optional. If one they want isn't listed, run `role add <team> <role>`. Then run `agent create <team> <agent name>`, with `--role <role>` for each role.
 
-## 4. Reload and check
+Then run `use <team> <agent name>` in the project root. It writes `.blether/session.json`, which git ignores.
 
-Tell the developer to restart this session (or run `/mcp` and reconnect the `blether` server) so the bridge picks up the project's agent.
+Done when the project has the agent they want, kept or set with `use`.
 
-Done when the bridge's `list_agents` shows the roster. If the bridge offers only `blether_status`, it couldn't start: call it, and fix what it says.
+## 4. Connect and check
 
-## 5. Push delivery and visibility
+Setting Blether up is a request to use it, so connect this session. Connecting takes the agent over from any other session connected as it, which is then disconnected without warning. So first run `agent list <team>`: if the project's agent shows as `online`, another session (perhaps in another terminal, or on another device) is using it. Tell them, and connect only if they say to take it over.
 
-Explain these two options and set up the ones they want:
+To connect, call the bridge's `connect` tool (`mcp__plugin_blether_blether__connect`; load it with ToolSearch first if it's deferred). It reads the project's agent when called, so there's no need to restart.
 
-- **Push delivery (channels)**: new messages can wake the session instead of waiting for the next mailbox check. Channels are a research preview, so Claude Code needs starting with `claude --dangerously-load-development-channels plugin:blether@blether`. Without it, nothing breaks; messages wait in the mailbox.
-- **Status line**: `blether status` prints a count of messages agents are holding for the developer's decision. Offer to add it to `statusLine` in `~/.claude/settings.json`, merging with any status line they already have.
+Done when it connects and its result's instructions are followed (read the mailbox, start the watch). If it fails, fix what it says.
+
+## 5. How it works, and visibility
+
+Tell them how Blether works from now on:
+
+- **Sessions start without Blether.** The bridge stays out of every session until they run `/blether:connect`. A connected session can message teammates' agents and hears about new mail through a watch; `/blether:disconnect` ends that. Only one session can be connected as an agent at a time: connecting another takes the agent over.
+
+Offer this option and set it up if they want it:
+
+- **Status line**: `blether status` prints a count of messages agents are holding for the developer's decision. Read `statusLine` in `~/.claude/settings.json` first: if it already runs `blether status`, say so and skip this. Otherwise, offer to add it, merging with any status line they already have.
 
 Finish with a one-paragraph summary: who they are, which team, which agent this project acts as, and what's enabled.