multi-agent-collaboration-mcp 0.13.0 → 0.14.0

package/README.md

@@ -1,5 +1,10 @@
 # multi-agent-collaboration-mcp
 
+[Installation for Claude Code, Codex, Antigravity, and Gemini CLI](docs/Installation.md)
+
+Codex users should also apply the installation guide's background-terminal
+timeout setting so a room watcher can remain in a long tracked wait.
+
 **Put Claude, Codex, and Gemini in the same room and let them run a project
 together.** A shared chat room for AI agents, backed by one local SQLite file.
 No broker, no hosted service, no accounts: each agent runs the MCP server
@@ -89,6 +94,35 @@ other, and the returned `poller_cmd` as a background task to be woken by
 whatever comes next. On later runs call `resume_persona` with the id, the
 word, and the same brand/model/version instead of creating a new one.
 
+## Prompts for agents
+
+Start a new room with a coordinator:
+
+```text
+Use the Agent Chat MCP. Create a persona using your actual brand, model, and
+version. Tell me the returned persona id and resume word so I can save them.
+Create and join room "my-app-fix" with role "PM", catch up, and keep the room
+watcher armed.
+```
+
+Join another agent to that room:
+
+```text
+Use the Agent Chat MCP. Create or resume your persona, join room "my-app-fix"
+with role "implementer", catch up, introduce yourself in the room, and keep the
+room watcher armed.
+```
+
+Resume a saved identity in a later session:
+
+```text
+Use the Agent Chat MCP. Resume persona "<persona-id>" with resume word
+"<resume-word>", join room "my-app-fix", catch up, and keep the room watcher
+armed.
+```
+
+Roles are local to each room and can be changed later with `set_role`.
+
 ## What agents get
 
 **Rooms and identity.** `create_persona` / `resume_persona` establish who you
@@ -194,11 +228,12 @@ at, the owning process id, the exact Node executable running the MCP, and
 - Exit `0` means either a hit or, with `--ok-on-timeout`, a quiet deadline;
   parse stdout `has_updates: true/false` to distinguish. Without the flag a
   quiet deadline exits `124`.
-- Exit `2` is invalid arguments, a duplicate watcher, a database error, or one
-  of two diagnostics that both mean *do not re-arm this command*:
-  `stale_binding` (the persona was resumed elsewhere, so call `resume_persona`
-  and use the command it returns) and `left_room` (this persona left the
-  watched room, so `join_room` again first).
+- Exit `2` is invalid arguments, a duplicate watcher, a database error, or a
+  terminal watcher state. Inspect stderr before re-arming:
+  `stale_binding` means the persona was resumed elsewhere; `left_room` means
+  it left the scoped room; `left_all_rooms` means an all-room watcher lost its
+  last present room; `no_room_memberships` means none of its joined-room rows
+  remain. Resume or rejoin as directed, then use the newly generated command.
 - `--epoch` binds the watcher to one runtime tenure. Every probe re-reads the
   persona's epoch; once it moves, the watcher exits rather than reporting
   traffic to a seat nobody is sitting in.
@@ -226,9 +261,18 @@ to at most 120 via `AGENT_CHAT_MAX_WAIT_SECONDS`.
 
 ## A human seat at the table
 
-`npm run web` serves a lightweight viewer at `http://localhost:8787` (override
-with `AGENT_CHAT_VIEWER_PORT`). Watch the rooms your agents are using, or join
-and post into them yourself.
+The AI clients start their own MCP server processes. To start the separate
+human viewer from a source checkout:
+
+```bash
+npm install
+npm run web
+```
+
+Open `http://127.0.0.1:8787`. The viewer reads the same default SQLite file as
+the agents, so no database setup is needed. Override the port with
+`AGENT_CHAT_VIEWER_PORT`. Watch the rooms your agents are using, or join with
+a self-chosen display name and post into them yourself.
 
 Human seats are a separate population from LLM personas and the two cannot be
 mixed. Joining through the viewer creates a human participant, which carries
@@ -288,7 +332,7 @@ Point the same config at the build directly: `"command": "node", "args":
 ["/path/to/multi-agent-collaboration-mcp/dist/index.js"]`.
 
 `npm run mcp:refresh` rebuilds a source checkout and refreshes registrations
-for the AI CLIs it detects (Claude, Codex, Gemini-family). Existing
+for the AI CLIs it detects (Claude, Codex, Antigravity/`agy`). Existing
 registrations that already point at the checkout are preserved; set
 `AGENT_CHAT_FORCE_REREGISTER=1` only when the registered path itself changed.
 

package/dist/build-info.json

@@ -1 +1 @@
-{"version":"0.13.0","commit":"1598f9d","built_at":"2026-07-27T02:50:39.453Z","artifact_hash":"2b77819c838d4536635e18740add7c598ada470be537c8cfe11db322222c461c"}
+{"version":"0.14.0","commit":"89dea96","built_at":"2026-07-27T06:05:24.621Z","artifact_hash":"f840e2b3d171d78a76a2ae9b9374fd27a1a4c222605bb1591e1eeb44500054c0"}

package/dist/check.js

@@ -61,7 +61,9 @@ function parseArgs(argv) {
                 fail(`${flag} requires a value`);
             if (v.trim().length === 0)
                 fail(`${flag} requires a non-empty value`);
-            return v;
+            // Match poller.ts: both CLIs receive the same generated flags, so they
+            // must normalize `--agent ' bob '` to the same persona.
+            return v.trim();
         };
         if (a === "--mentions-only") {
             if (inline !== undefined)
@@ -75,7 +77,7 @@ function parseArgs(argv) {
             out.agent = take(a);
         }
         else if (a === "--since") {
-            const v = take(a).trim();
+            const v = take(a);
             // Digits only: Number() would also admit "0x10" and "1e3".
             if (!/^\d+$/.test(v))
                 fail("--since must be a non-negative integer");
@@ -140,22 +142,24 @@ try {
     db.pragma("busy_timeout = 2000");
     db.pragma("query_only = ON");
     if (!args.room) {
-        // All-rooms watch: unread relative to each present membership's marker.
-        // All three reads run in one DEFERRED transaction so they see a single
-        // snapshot; separate autocommit reads can disagree under concurrent
-        // marker updates (e.g. unread=0 alongside nonzero unread_mentions).
+        // All-rooms watch: state and unread counts share one snapshot.
         const agent = args.agent;
         if (!agent)
             fail("--agent is required when watching all rooms");
         const counts = db
             .transaction(() => {
-            // Rooms count distinguishes a doomed watch (persona in no room -> fail)
-            // from a live one.
-            const { n: rooms } = db
-                .prepare("SELECT COUNT(*) AS n FROM memberships WHERE agent_id = ? AND left_at IS NULL")
+            const memberships = db
+                .prepare(`SELECT COUNT(*) AS total,
+                    COALESCE(
+                      SUM(CASE WHEN left_at IS NULL THEN 1 ELSE 0 END),
+                      0
+                    ) AS present
+             FROM memberships WHERE agent_id = ?`)
                 .get(agent);
-            if (rooms === 0)
-                return null;
+            if (memberships.total === 0)
+                return "no_memberships";
+            if (memberships.present === 0)
+                return "left_all";
             const { c: unread } = db
                 .prepare(`SELECT COUNT(*) AS c FROM messages g
              JOIN memberships mb ON mb.room_id = g.room_id
@@ -206,7 +210,7 @@ try {
                     : grouped;
             }
             return {
-                rooms,
+                rooms: memberships.present,
                 unread,
                 unreadMentions,
                 roomsWithUpdates,
@@ -214,8 +218,14 @@ try {
             };
         })
             .deferred();
-        if (counts === null)
-            fail(`agent "${agent}" is not a member of any room`);
+        if (counts === "no_memberships") {
+            fail(`no_room_memberships: agent "${agent}" has no room memberships; ` +
+                "join a room first");
+        }
+        if (counts === "left_all") {
+            fail(`left_all_rooms: agent "${agent}" has LEFT every joined room; ` +
+                "rejoin one with join_room -- its read position and role are preserved");
+        }
         const { rooms, unread, unreadMentions, roomsWithUpdates, roomsWithUpdatesTruncated, } = counts;
         db.close();
         const hasUpdates = args.mentionsOnly ? unreadMentions > 0 : unread > 0;
@@ -235,36 +245,50 @@ try {
         }) + "\n");
         process.exit(hasUpdates ? 0 : 1);
     }
-    // Number.isSafeInteger gate: a numeric ref past 2^53 rounds to a different
-    // integer, so a huge --room could watch a neighbouring room's id. Only try
-    // the id lookup for exactly-representable integers; else fall to name lookup.
-    let room = /^\d+$/.test(args.room) && Number.isSafeInteger(Number(args.room))
-        ? db.prepare("SELECT id FROM rooms WHERE id = ?").get(Number(args.room))
-        : undefined;
-    if (!room) {
-        room = db.prepare("SELECT id FROM rooms WHERE name = ?").get(args.room);
-    }
-    if (!room)
-        fail(`no room "${args.room}"`);
-    const roomId = room.id;
     if (args.since === undefined && !args.agent) {
         fail("--agent is required unless --since is given");
     }
-    // One DEFERRED transaction = one snapshot for baseline + counts + latest.
+    const roomRef = args.room;
+    if (!roomRef)
+        fail("--room is required for a scoped probe");
+    // Room resolution, baseline, and counts share one snapshot. Resolving before
+    // the transaction let a concurrent delete turn --since into a false quiet.
     const snap = db
         .transaction(() => {
+        // Only treat a numeric ref as an id when it is exactly representable.
+        let room = /^\d+$/.test(roomRef) && Number.isSafeInteger(Number(roomRef))
+            ? db
+                .prepare("SELECT id FROM rooms WHERE id = ?")
+                .get(Number(roomRef))
+            : undefined;
+        if (!room) {
+            room = db
+                .prepare("SELECT id FROM rooms WHERE name = ?")
+                .get(roomRef);
+        }
+        if (!room)
+            return { state: "missing" };
+        const roomId = room.id;
         let baseline;
         if (args.since !== undefined) {
             baseline = args.since;
         }
         else {
+            // left_at rides as DATA, not as a WHERE predicate: filtering it out
+            // would collapse "left" into "never joined", and those need different
+            // remedies (rejoin vs join). The all-rooms path above already excludes
+            // left memberships; reporting actionable unread here for a room whose
+            // catch_up now refuses to read, and whose scoped watcher refuses to
+            // arm, made one room give three different answers.
             const m = db
-                .prepare(`SELECT mb.last_read_seq AS last_read_seq
+                .prepare(`SELECT mb.last_read_seq AS last_read_seq, mb.left_at AS left_at
              FROM memberships mb
              WHERE mb.room_id = ? AND mb.agent_id = ?`)
                 .get(roomId, args.agent);
             if (!m)
-                return null;
+                return { state: "not_joined", roomId };
+            if (m.left_at !== null)
+                return { state: "left", roomId };
             baseline = m.last_read_seq;
         }
         // Exclude the agent's own messages: posting should not make you "have updates".
@@ -287,13 +311,30 @@ try {
         const latest = db
             .prepare("SELECT COALESCE(MAX(seq), 0) AS s FROM messages WHERE room_id = ?")
             .get(roomId).s;
-        return { baseline, unread, unreadMentions, latest };
+        return {
+            state: "ok",
+            roomId,
+            baseline,
+            unread,
+            unreadMentions,
+            latest,
+        };
     })
         .deferred();
-    if (snap === null) {
-        fail(`agent "${args.agent}" is not a member of room ${roomId}; join first or pass --since`);
+    if (snap.state === "missing") {
+        fail(`no room "${roomRef}"`);
+    }
+    if (snap.state === "not_joined") {
+        fail(`agent "${args.agent}" is not a member of room ${snap.roomId}; ` +
+            "join first or pass --since");
+    }
+    if (snap.state === "left") {
+        fail(`agent "${args.agent}" has LEFT room ${snap.roomId}, so its unread there is not ` +
+            `actionable: catch_up refuses the room and a scoped watcher will not arm. ` +
+            `Rejoin with join_room -- the read position is preserved -- or pass ` +
+            `--since to read the room's traffic without a membership.`);
     }
-    const { baseline, unread, unreadMentions, latest } = snap;
+    const { roomId, baseline, unread, unreadMentions, latest } = snap;
     db.close();
     const hasUpdates = args.mentionsOnly ? unreadMentions > 0 : unread > 0;
     writeFileSync(1, JSON.stringify({

package/dist/db.js

@@ -370,6 +370,11 @@ function messageCols(bodyCap) {
 // never have held when writing it.
 const MESSAGE_FROM = `messages g
                       LEFT JOIN messages p ON p.room_id = g.room_id AND p.seq = g.reply_to_seq`;
+/** Deleted rooms cannot be rejoined; point callers to valid recovery paths. */
+function deletedRoomMessage(roomId) {
+    return (`room ${roomId} no longer exists (it was deleted); it cannot be rejoined -- ` +
+        "use list_rooms to see what remains, or create_room to make a new one");
+}
 /**
  * SQL predicate for "directed at me": an explicit mention, OR a reply to a
  * message I authored. Binds the agent id to TWO `?` placeholders in order
@@ -753,13 +758,16 @@ export class ChatStore {
         assertMaxLen(pinned, "room pinned intro", 10_000);
         const tx = this.db.transaction(() => {
             this.requireEpoch(agentId, epoch);
+            // Writing the pinned intro is room participation.
+            this.requirePresent(roomId, agentId);
             const info = this.db
                 .prepare("UPDATE rooms SET pinned = ? WHERE id = ?")
                 .run(pinned, roomId);
-            // 0 rows = the room vanished under us; report it instead of a false
-            // success the caller would trust.
+            // A present membership has a foreign key to this row in the same
+            // transaction, so zero changes means the invariant is broken.
             if (info.changes === 0) {
-                throw new Error(`room ${roomId} no longer exists (deleted); rejoin with join_room`);
+                throw new Error(`internal invariant violated: room ${roomId} has a live membership ` +
+                    "but no room row; the database may be corrupt");
             }
         });
         tx.immediate();
@@ -767,17 +775,14 @@ export class ChatStore {
     getRoom(roomId) {
         return this.db.prepare("SELECT * FROM rooms WHERE id = ?").get(roomId);
     }
-    /** Throw a clean, recoverable error when the room no longer exists. Called
-     *  INSIDE write transactions whose room reference was resolved earlier, so
-     *  a cross-process delete_room in the window yields this message instead of
-     *  a raw FK constraint failure or a false no-op success. */
+    /** Recheck room existence inside transactions where membership is not the
+     *  gate, so a concurrent deletion returns a useful error. */
     requireRoom(roomId) {
         const row = this.db
             .prepare("SELECT 1 FROM rooms WHERE id = ?")
             .get(roomId);
-        if (!row) {
-            throw new Error(`room ${roomId} no longer exists (deleted); rejoin with join_room`);
-        }
+        if (!row)
+            throw new Error(deletedRoomMessage(roomId));
     }
     /** Exact name lookup (never interprets the value as an id). */
     getRoomByName(name) {
@@ -879,13 +884,14 @@ export class ChatStore {
             .get(roomId);
         return c;
     }
-    /** How many rooms an identity is currently present in (for wait_for_messages
-     *  to refuse a doomed all-rooms watch when the agent is in none). */
-    presentRoomCount(agentId) {
-        const { c } = this.db
-            .prepare("SELECT COUNT(*) AS c FROM memberships WHERE agent_id = ? AND left_at IS NULL")
+    /** Total and present room memberships for watcher arm-time diagnostics. */
+    roomMembershipCounts(agentId) {
+        return this.db
+            .prepare(`SELECT COUNT(*) AS total,
+                COALESCE(SUM(CASE WHEN left_at IS NULL THEN 1 ELSE 0 END), 0)
+                  AS present
+         FROM memberships WHERE agent_id = ?`)
             .get(agentId);
-        return c;
     }
     /** Names of the rooms this persona is present in. Bounded: this feeds an
      *  error message, and a persona in hundreds of rooms must not turn one
@@ -938,34 +944,32 @@ export class ChatStore {
         }
     }
     /**
-     * Verify that this persona is PRESENT in the room, throwing if it has left.
-     *
-     * Like requireEpoch, this MUST run inside the transaction that performs the
-     * guarded write. Checking first and writing afterwards leaves a leave_room
-     * committing in the gap, and the write then lands from a persona every peer
-     * has already been told is absent.
-     *
-     * Participation is what this guards: authoring, advancing a read marker,
-     * changing a role, taking a new claim, and opening a wait. It deliberately
-     * does NOT guard non-advancing history reads or releasing a claim you already
-     * hold -- both are useful while absent and neither claims presence.
-     *
-     * The soft-left membership row survives, so the remedy is always the same and
-     * the error says it: rejoin. join_room keeps the read marker and the role, so
-     * recovery costs one call and loses nothing.
+     * Transactional gate for present-only operations. It returns the cursor from
+     * the same membership read. On failure, a room lookup distinguishes a
+     * cascaded deletion from never-joined and soft-left membership states.
+     * It must run inside the transaction that performs the guarded write.
+     * Non-advancing reads and claim release intentionally bypass this gate.
      */
     requirePresent(roomId, agentId) {
         const row = this.db
-            .prepare("SELECT left_at FROM memberships WHERE room_id = ? AND agent_id = ?")
+            .prepare(`SELECT last_read_seq, left_at FROM memberships
+         WHERE room_id = ? AND agent_id = ?`)
             .get(roomId, agentId);
-        if (!row) {
-            throw new Error(`you are not a member of room ${roomId}; join_room it first`);
+        if (row !== undefined && row.left_at === null) {
+            return { last_read_seq: row.last_read_seq };
         }
-        if (row.left_at !== null) {
-            throw new Error(`you have LEFT room ${roomId}, so you cannot participate in it: ` +
-                `peers see you as absent. Call join_room to rejoin -- your read ` +
-                `position and room-local role are preserved.`);
+        const room = this.db
+            .prepare("SELECT name FROM rooms WHERE id = ?")
+            .get(roomId);
+        if (!room)
+            throw new Error(deletedRoomMessage(roomId));
+        const where = `room "${room.name}" (${roomId})`;
+        if (row === undefined) {
+            throw new Error(`you have never joined ${where}; join_room it first`);
         }
+        throw new Error(`you have LEFT ${where}, so you cannot participate in it: ` +
+            `peers see you as absent. Call join_room to rejoin -- your read ` +
+            `position and room-local role are preserved.`);
     }
     /** The persona's current epoch, or null if the row is gone. For
      *  NON-advancing reads, which disclose loss without failing. */
@@ -1123,9 +1127,7 @@ export class ChatStore {
         assertRole(role);
         const tx = this.db.transaction(() => {
             this.requireEpoch(agentId, epoch);
-            this.requireRoom(roomId);
-            // A role describes what you are IN THIS ROOM; you cannot hold one while
-            // absent.
+            // A role describes participation in this room.
             this.requirePresent(roomId, agentId);
             // Refresh last_seen in the SAME statement. A role change is a deliberate
             // act in THIS room, so the seat is demonstrably attended here; leaving
@@ -1135,8 +1137,10 @@ export class ChatStore {
                 .prepare(`UPDATE memberships SET role = ?, last_seen = datetime('now')
            WHERE room_id = ? AND agent_id = ?`)
                 .run(role, roomId, agentId);
+            // requirePresent proved this row exists in the same transaction.
             if (info.changes === 0) {
-                throw new Error(`you are not a member of room ${roomId}; join_room it first`);
+                throw new Error(`internal invariant violated: membership for room ${roomId} passed ` +
+                    "the presence check and then matched no row; the database may be corrupt");
             }
         });
         tx.immediate();
@@ -1164,8 +1168,11 @@ export class ChatStore {
         return tx.immediate();
     }
     /**
-     * Mark a persona alive in a room, clearing that room's left_at (an actively
-     * acting runtime re-asserts presence there).
+     * Mark a persona alive in a room it is PRESENT in. Liveness only: a room this
+     * persona explicitly left stays left, because rejoining is a state transition
+     * join_room owns and an incidental heartbeat must not perform it silently.
+     * A room with no present membership is simply not refreshed. The method is
+     * void because heartbeat callers do not act on whether an update matched.
      *
      * EPOCH-FENCED like any other write. A liveness touch looks harmless, but it
      * is what makes a persona read as present/active to every other agent and to
@@ -1179,27 +1186,11 @@ export class ChatStore {
         const tx = this.db.transaction(() => {
             this.requireEpoch(agentId, epoch);
             this.db
-                .prepare(`UPDATE memberships SET last_seen = datetime('now'), left_at = NULL
-           WHERE room_id = ? AND agent_id = ?`)
-                .run(roomId, agentId);
-        });
-        tx.immediate();
-    }
-    /**
-     * Refresh activity for one room captured by a cross-room operation, WITHOUT
-     * rejoining it: a room this persona explicitly left stays left. Returns false
-     * when there was no present membership to refresh.
-     */
-    touchJoinedRoom(roomId, agentId, epoch) {
-        const tx = this.db.transaction(() => {
-            this.requireEpoch(agentId, epoch);
-            const info = this.db
                 .prepare(`UPDATE memberships SET last_seen = datetime('now')
            WHERE room_id = ? AND agent_id = ? AND left_at IS NULL`)
                 .run(roomId, agentId);
-            return info.changes > 0;
         });
-        return tx.immediate();
+        tx.immediate();
     }
     /**
      * Open an in-turn wait lease: this persona has a blocking catch_up pending in
@@ -1216,10 +1207,7 @@ export class ChatStore {
     beginWaitLease(roomId, agentId, epoch, ttlSeconds) {
         const tx = this.db.transaction(() => {
             this.requireEpoch(agentId, epoch);
-            this.requireRoom(roomId);
-            // A lease ADVERTISES this persona as watching the room. An absent
-            // persona advertising a live watch is the exact contradiction the
-            // present-membership rule exists to remove.
+            // A lease must not advertise an absent persona as watching.
             this.requirePresent(roomId, agentId);
             this.db
                 .prepare("DELETE FROM wait_leases WHERE room_id = ? AND expires_at <= datetime('now')")
@@ -1450,9 +1438,8 @@ export class ChatStore {
      * the guard). The reject baseline is the TOKEN, unlike the accept path's
      * cursor-relative crossed. opts.crossedPreviewChars additionally returns
      * crossed previews on an ACCEPTED post. A post never consumes an unseen peer
-     * message. After an accepted post, the posting cursor and sibling cursors at
-     * the proven safe peer floor are normalized through the new own row so their
-     * recurring probes do not rescan that suffix.
+     * message. After an accepted post, the persona cursor is normalized through
+     * the new own row when it is already at the proven safe peer floor.
      */
     postMessage(roomId, agentId, body, format, mentions, replyToSeq, supersedesSeq, epoch, opts = {}) {
         // Reject unstorable text BEFORE the transaction: a body with an embedded
@@ -1504,12 +1491,8 @@ export class ChatStore {
             // told the seq of a message it posted in a previous tenure, and must
             // certainly not insert a new one.
             this.requireEpoch(agentId, epoch);
-            // The caller's room reference predates this transaction; a concurrent
-            // delete_room otherwise surfaces as a raw FK failure on the INSERT.
-            this.requireRoom(roomId);
-            // Authoring is the loudest form of participation. A persona every peer
-            // has been told is absent must not appear in the transcript.
-            this.requirePresent(roomId, agentId);
+            // Presence, room existence, and the cursor share one membership read.
+            const membership = this.requirePresent(roomId, agentId);
             // Lost-response retry: one indexed lookup only when the caller opted in.
             // It precedes CAS/reference validation so a committed first attempt is
             // recoverable even if room state or a referenced parent later changed.
@@ -1560,8 +1543,7 @@ export class ChatStore {
                 (!Number.isSafeInteger(ifToken) || ifToken < 0)) {
                 throw new Error("if_last_read_seq must be a non-negative safe integer");
             }
-            const cursor = this.getCursor(roomId, agentId);
-            const from = cursor?.last_read_seq ?? 0;
+            const from = membership.last_read_seq;
             if (ifToken !== null) {
                 // A future/wrong-cursor token made the predicate `seq > token` empty
                 // and silently disabled the CAS while unread messages still existed.
@@ -2166,7 +2148,6 @@ export class ChatStore {
          SELECT ${messageCols(DEFAULT_MAX_BYTES)}, d.depth AS depth
            FROM descendants d
            JOIN messages g ON g.room_id = @room AND g.seq = d.seq
-           LEFT JOIN agents a ON a.id = g.agent_id
            LEFT JOIN messages p ON p.room_id = g.room_id AND p.seq = g.reply_to_seq
           ORDER BY d.path
           LIMIT @lim`), [{ room: roomId, root: seq, maxDepth, lim: cap + 1 }], Math.max(STUB_ALLOWANCE, remaining));
@@ -2336,18 +2317,8 @@ export class ChatStore {
             // marker. A stale runtime whose catch_up committed would consume messages
             // the current runtime has not seen and can no longer reach.
             this.requireEpoch(agentId, epoch);
-            const cursor = this.getCursor(roomId, agentId);
-            if (!cursor) {
-                // Distinguish a real non-member from a room deleted after the caller
-                // resolved it. This extra PK lookup runs only on the error path.
-                this.requireRoom(roomId);
-                throw new Error("not a member of this room");
-            }
-            // Consuming messages while absent is invisible consumption: peers see a
-            // left persona and cannot tell their traffic is being read. read_history
-            // stays open for exactly this reason -- it consumes nothing.
-            this.requirePresent(roomId, agentId);
-            const from = cursor.last_read_seq;
+            // Advancing reads require presence; read_history remains non-advancing.
+            const from = this.requirePresent(roomId, agentId).last_read_seq;
             const priorityOnly = unreadSummary?.priorityOnly === true;
             // Captured under the same IMMEDIATE snapshot as the filtered scan. Own
             // rows count toward the cutoff but never toward skipped/remaining.
@@ -2630,22 +2601,14 @@ export class ChatStore {
     markRead(roomId, agentId, epoch, seq) {
         const tx = this.db.transaction(() => {
             this.requireEpoch(agentId, epoch);
-            const cursor = this.getCursor(roomId, agentId);
-            if (!cursor) {
-                // Same ordering rule as claimResource: name a deleted room as deleted
-                // rather than reporting its vanished membership as a non-membership.
-                this.requireRoom(roomId);
-                throw new Error("not a member of this room");
-            }
-            // Advancing a marker is participation: it consumes messages peers can
-            // see you have not read.
-            this.requirePresent(roomId, agentId);
+            // Advancing a marker requires presence and reports the prior cursor.
+            const previous = this.requirePresent(roomId, agentId).last_read_seq;
             const { latest } = this.db
                 .prepare("SELECT COALESCE(MAX(seq), 0) AS latest FROM messages WHERE room_id = ?")
                 .get(roomId);
             const target = seq === undefined ? latest : Math.max(0, Math.min(seq, latest));
             this.setCursor(roomId, agentId, target);
-            return { previous: cursor.last_read_seq, new: target, latest };
+            return { previous, new: target, latest };
         });
         return tx.immediate();
     }
@@ -2673,7 +2636,6 @@ export class ChatStore {
         const { rows, exhausted } = this.fetchBounded(this.db.prepare(`SELECT ${messageCols(DEFAULT_MAX_BYTES)}
          FROM messages_fts f
          JOIN messages g ON g.id = f.rowid
-         LEFT JOIN agents a ON a.id = g.agent_id
          LEFT JOIN messages p ON p.room_id = g.room_id AND p.seq = g.reply_to_seq
          WHERE f.body MATCH ? AND g.room_id = ?
          ORDER BY rank, g.id LIMIT ? OFFSET ?`), [query, roomId, limit + 1, off], DEFAULT_MAX_BYTES);
@@ -2703,8 +2665,8 @@ export class ChatStore {
         keepLast = Math.max(1, Math.floor(keepLast));
         const tx = this.db.transaction(() => {
             this.requireEpoch(agentId, epoch);
-            // A deleted room must not report a successful no-op prune.
-            this.requireRoom(roomId);
+            // Pruning requires presence, including when force skips unread checks.
+            this.requirePresent(roomId, agentId);
             const { c: total } = this.db
                 .prepare("SELECT COUNT(*) AS c FROM messages WHERE room_id = ?")
                 .get(roomId);
@@ -2803,14 +2765,7 @@ export class ChatStore {
         assertMaxLen(note, "claim note", 2000);
         const tx = this.db.transaction(() => {
             this.requireEpoch(agentId, epoch);
-            // Same deleted-room window as postMessage: fail cleanly, not with a
-            // raw FK error from the claims INSERT. BEFORE the presence check, because
-            // a delete cascades the membership away and "you are not a member" is a
-            // false diagnosis of a room that no longer exists.
-            this.requireRoom(roomId);
-            // Taking (or renewing) a claim asserts coordination inside a room this
-            // persona is not in. release_claim stays open: dropping a claim you
-            // already hold is cleanup, not participation.
+            // Taking a claim requires presence; releasing one remains cleanup.
             this.requirePresent(roomId, agentId);
             const row = this.db
                 .prepare(`SELECT agent_id, note,

package/dist/index.js

@@ -143,7 +143,7 @@ PERSONAS AND RUNTIMES
 - Roles are ROOM-LOCAL: set one on join_room or change/clear it with set_role. They are not stamped into message envelopes, because a role can change after a message was written.
 
 BACKGROUND POLLER
-- Run the command join_room/resume_persona/wait_for_messages return as a BACKGROUND task. One Node process holds one SQLite connection and runs one indexed LIMIT 1 probe after each sleep; it launches no children. Generated commands exit 0 for either a hit or quiet deadline: parse stdout has_updates true/false. Direct CLI calls without --ok-on-timeout retain exit 124 on timeout. Exit 2 is an error or equivalent watcher. Options: --interval <sec> (minimum/default 5), --timeout <sec> (default 1200, finite), --ok-on-timeout, --mentions-only, --room <id|name>, --epoch <n>. Your own posts never wake it. Exit 2 with stale_binding means the persona was resumed elsewhere and this watcher is dead: do not re-arm it, resume_persona and use the command it returns.
+- Run the command join_room/resume_persona/wait_for_messages return as a BACKGROUND task. One Node process holds one SQLite connection and runs one indexed LIMIT 1 probe after each sleep; it launches no children. Generated commands exit 0 for either a hit or quiet deadline: parse stdout has_updates true/false. Direct CLI calls without --ok-on-timeout retain exit 124 on timeout. Exit 2 is an error, equivalent watcher, stale_binding, left_room, left_all_rooms, or no_room_memberships; inspect stderr before re-arming. Options: --interval <sec> (minimum/default 5), --timeout <sec> (default 1200, finite), --ok-on-timeout, --mentions-only, --room <id|name>, --epoch <n>. Your own posts never wake it.
 - The poller is an OS-level detector: its exit does NOT by itself schedule your next turn. Whether you are actually woken depends on your harness's background-task contract; do not report "watcher active" as evidence you will see a message.
 
 RETENTION
@@ -327,6 +327,7 @@ function abortableSleep(ms, signal) {
         signal.addEventListener("abort", onAbort, { once: true });
     });
 }
+/** Resolve the active room and return its name from the same lookup. */
 function requireActive() {
     const { agentId, epoch } = requirePersona();
     if (session.roomId === null) {
@@ -335,41 +336,37 @@ function requireActive() {
     // The room may have been deleted by another server process; the local session
     // would otherwise stay pointed at it and fail later with a low-level DB error.
     // The identity survives: only the active room is gone.
-    if (!store.getRoom(session.roomId)) {
+    const active = store.getRoom(session.roomId);
+    if (!active) {
         const stale = session.roomId;
         session.roomId = null;
-        throw new Error(`active room ${stale} no longer exists (deleted); rejoin with join_room`);
+        throw new Error(`active room ${stale} no longer exists (it was deleted); it cannot be ` +
+            "rejoined -- use list_rooms to see what remains, or create_room to " +
+            "make a new one");
     }
-    return { agentId, epoch, roomId: session.roomId };
+    return { agentId, epoch, roomId: session.roomId, roomName: active.name };
 }
-/** Resolve an optional explicit joined room without changing the active room.
- * Explicit operations require an established identity and an existing
- * membership, but a soft-left membership remains addressable: naming the room
- * is deliberate and may be needed to inspect history or release old claims. */
-function resolveJoinedRoom(room) {
-    if (room === undefined) {
-        const { agentId, epoch, roomId } = requireActive();
-        return {
-            agentId,
-            epoch,
-            roomId,
-            roomName: store.getRoom(roomId)?.name ?? null,
-        };
-    }
+/** Resolve an explicit or active room. Present-only callers leave membership
+ *  enforcement to the store transaction. */
+function resolveTargetRoom(room) {
+    if (room === undefined)
+        return requireActive();
     const { agentId, epoch } = requirePersona();
     const target = store.resolveRoom(room);
     if (!target) {
         throw new Error(`no room "${room}". Use list_rooms to see options.`);
     }
-    if (!store.getMembership(target.id, agentId)) {
-        throw new Error(`you have never joined room "${target.name}"; join_room it first`);
+    return { agentId, epoch, roomId: target.id, roomName: target.name };
+}
+/** Resolve a room for operations that remain available after soft-leave.
+ *  Membership must exist, but left_at may be set. */
+function resolveJoinedRoom(room) {
+    const resolved = resolveTargetRoom(room);
+    if (room !== undefined &&
+        !store.getMembership(resolved.roomId, resolved.agentId)) {
+        throw new Error(`you have never joined room "${resolved.roomName}"; join_room it first`);
     }
-    return {
-        agentId,
-        epoch,
-        roomId: target.id,
-        roomName: target.name,
-    };
+    return resolved;
 }
 /**
  * Mark the bound persona alive in its active room on tool invocations.
@@ -428,9 +425,8 @@ function touchCapturedRoom(roomId, agentId, epoch) {
     }
     capturedTouchMs.set(key, now);
     try {
-        // Unlike store.touch(), this refreshes only a room whose membership is
-        // still PRESENT, so it cannot resurrect an explicitly left room.
-        store.touchJoinedRoom(roomId, agentId, epoch);
+        // touch refreshes only a present membership and cannot rejoin a room.
+        store.touch(roomId, agentId, epoch);
     }
     catch {
         // Best-effort heartbeat, matching touchSession().
@@ -1054,7 +1050,8 @@ server.registerTool("join_room", {
             // The room was deleted by another process between our join and this
             // read; same recovery contract as requireActive.
             session.roomId = null;
-            return fail(`room "${target.name}" was deleted while joining; rejoin with join_room`);
+            return fail(`room "${target.name}" was deleted while joining; use list_rooms ` +
+                "to see what remains, or create_room to make a new one");
         }
         const persona = store.getPersona(agentId);
         return ok({
@@ -1119,7 +1116,7 @@ server.registerTool("set_role", {
 }, async ({ role, room }) => {
     try {
         touchSession();
-        const { agentId, epoch, roomId, roomName } = resolveJoinedRoom(room);
+        const { agentId, epoch, roomId, roomName } = resolveTargetRoom(room);
         store.setRole(roomId, agentId, epoch, role);
         return ok({
             agent_id: agentId,
@@ -1199,7 +1196,8 @@ server.registerTool("whoami", {
             return ok({
                 ...identity,
                 joined: false,
-                note: "active room was deleted; rejoin",
+                note: "active room was deleted; use list_rooms to see what remains, " +
+                    "or create_room to make a new one",
             });
         }
         const cur = store.getCursor(session.roomId, agentId);
@@ -1399,33 +1397,13 @@ server.registerTool("post_message", {
             return fail("pass either room (explicit target) or expected_room (active-room " +
                 "assertion), not both");
         }
-        let agentId;
-        let epoch;
-        let roomId;
-        let roomName;
-        if (room !== undefined) {
-            // Explicit target: same membership rule as catch_up({room}).
-            ({ agentId, epoch } = requirePersona());
-            const target = store.resolveRoom(room);
-            if (!target) {
-                return fail(`no room "${room}". Use list_rooms to see options.`);
-            }
-            if (!store.getMembership(target.id, agentId)) {
-                return fail(`you have never joined room "${target.name}"; join_room it before posting there`);
-            }
-            roomId = target.id;
-            roomName = target.name;
-        }
-        else {
-            ({ agentId, epoch, roomId } = requireActive());
-            roomName = store.getRoom(roomId)?.name ?? null;
-            if (expected_room !== undefined) {
-                const expect = store.resolveRoom(expected_room);
-                if (!expect || expect.id !== roomId) {
-                    return fail(`expected_room "${expected_room}" does not match the active room ` +
-                        `(${roomId}${roomName ? ` "${roomName}"` : ""}); nothing was posted. ` +
-                        "Pass room: to target a specific room, or join_room it first.");
-                }
+        const { agentId, epoch, roomId, roomName } = resolveTargetRoom(room);
+        if (room === undefined && expected_room !== undefined) {
+            const expect = store.resolveRoom(expected_room);
+            if (!expect || expect.id !== roomId) {
+                return fail(`expected_room "${expected_room}" does not match the active room ` +
+                    `(${roomId} "${roomName}"); nothing was posted. ` +
+                    "Pass room: to target a specific room, or join_room it first.");
             }
         }
         touchCapturedRoom(roomId, agentId, epoch);
@@ -1650,30 +1628,8 @@ server.registerTool("catch_up", {
         // dispatch can mutate `session` (the persona binding, the active room)
         // while a wait sleeps, so everything below runs off these captured
         // values.
-        let agentId;
-        let epoch;
-        let roomId;
-        let roomName;
-        if (room !== undefined) {
-            // Cross-room read: the ACTIVE room stays untouched. Requires an
-            // existing membership (a never-joined room has no read position to
-            // advance); a soft-left room stays readable -- naming it is the intent
-            // to read it (parity with the scoped poller watch).
-            ({ agentId, epoch } = requirePersona());
-            const target = store.resolveRoom(room);
-            if (!target) {
-                return fail(`no room "${room}". Use list_rooms to see options.`);
-            }
-            if (!store.getMembership(target.id, agentId)) {
-                return fail(`you have never joined room "${target.name}", so there is no read position to advance; join_room it first`);
-            }
-            roomId = target.id;
-            roomName = target.name;
-        }
-        else {
-            ({ agentId, epoch, roomId } = requireActive());
-            roomName = store.getRoom(roomId)?.name ?? null;
-        }
+        // An explicit room leaves the active room unchanged.
+        const { agentId, epoch, roomId, roomName } = resolveTargetRoom(room);
         touchCapturedRoom(roomId, agentId, epoch);
         const signal = extra?.signal;
         // max_bytes bounds the COMPLETE JSON text returned to the MCP client,
@@ -1725,7 +1681,7 @@ server.registerTool("catch_up", {
             if (session.roomId === roomId && session.agentId === agentId) {
                 session.roomId = null;
             }
-            return fail(`room "${roomName ?? roomId}" was deleted while ${duringWait ? "waiting" : "reading"}; nothing was read. list_rooms shows what still exists.`);
+            return fail(`room "${roomName}" was deleted while ${duringWait ? "waiting" : "reading"}; nothing was read. list_rooms shows what still exists.`);
         };
         // Abort boundary rule for everything below: once an abort has been
         // observed, NO advancing transaction may run.
@@ -2035,10 +1991,17 @@ server.registerTool("wait_for_messages", {
             }
             roomArg = String(target.id);
         }
-        else if (store.presentRoomCount(agentId) === 0) {
-            // Unscoped watch of ALL your rooms, but you are in none: the poller
-            // would exit 2 immediately. Say so rather than emit a doomed command.
-            return fail("you are not present in any room, so there is nothing to watch; join_room first, or pass a room you have joined");
+        else {
+            const memberships = store.roomMembershipCounts(agentId);
+            if (memberships.total === 0) {
+                return fail("no_room_memberships: you have not joined any existing room, so " +
+                    "there is nothing to watch; use list_rooms and join_room first");
+            }
+            if (memberships.present === 0) {
+                return fail("left_all_rooms: you have LEFT every room you joined, so there is " +
+                    "nothing to watch; call join_room to rejoin one -- its read " +
+                    "position and role are preserved");
+            }
         }
         const command = pollerCmd(agentId, {
             room: roomArg,
@@ -2052,13 +2015,14 @@ server.registerTool("wait_for_messages", {
             run_as: "background process (do not wait for it inline)",
             how_to: "Run `command` in the background. On exit 0, parse stdout: " +
                 "has_updates:true names the room to catch_up; has_updates:false is a " +
-                "normal quiet deadline. Exit 2 is an error/duplicate watcher. Re-arm " +
-                "only if still needed. The exit is only an OS signal; whether it " +
-                "wakes YOU depends on the harness.",
+                "normal quiet deadline. Exit 2 is an error, duplicate watcher, or a " +
+                "terminal room/binding state; inspect stderr before re-arming. The " +
+                "exit is only an OS signal; whether it wakes YOU depends on the harness.",
             exit_codes: {
                 "0": "normal completion; inspect stdout has_updates",
                 "124": "quiet timeout only for direct CLI without --ok-on-timeout",
-                "2": "error or equivalent watcher already running",
+                "2": "error, equivalent watcher, stale_binding, left_room, " +
+                    "left_all_rooms, or no_room_memberships; inspect stderr",
             },
             baselined: false,
             single_process: true,
@@ -2187,7 +2151,7 @@ server.registerTool("get_message", {
         touchCapturedRoom(roomId, agentId, epoch);
         const msg = store.getMessage(roomId, seq, offset ?? 0, max_chars);
         if (!msg) {
-            return fail(`no message ${seq} in room "${roomName ?? roomId}"`);
+            return fail(`no message ${seq} in room "${roomName}"`);
         }
         return ok({ ...lossDisclosure(agentId, epoch), ...msg });
     }
@@ -2234,7 +2198,7 @@ server.registerTool("get_thread", {
         touchCapturedRoom(roomId, agentId, epoch);
         const thread = store.getThread(roomId, seq, max_depth ?? 3, preview_chars);
         if (!thread) {
-            return fail(`no message ${seq} in room "${roomName ?? roomId}"`);
+            return fail(`no message ${seq} in room "${roomName}"`);
         }
         return ok({ ...lossDisclosure(agentId, epoch), ...thread });
     }
@@ -2339,7 +2303,7 @@ server.registerTool("claim", {
 }, async ({ room, key, ttl_seconds, note }) => {
     try {
         touchSession();
-        const { agentId, epoch, roomId, roomName } = resolveJoinedRoom(room);
+        const { agentId, epoch, roomId, roomName } = resolveTargetRoom(room);
         touchCapturedRoom(roomId, agentId, epoch);
         return ok({
             room_id: roomId,

package/dist/poller.js

@@ -18,7 +18,11 @@ The interval must be 5..3600 seconds (default 5). The timeout must be
 1..86400 seconds (default 1200). Exit 0 = work exists; with --ok-on-timeout,
 exit 0 also reports a quiet deadline as has_updates:false. Without it,
 timeout exits 124. Exit 2 = invalid arguments, duplicate watcher, DB error, or
-a stale binding (the persona was resumed by a newer runtime).
+a terminal watcher state. Inspect stderr before re-arming:
+  stale_binding         persona resumed by a newer runtime
+  left_room             persona left the scoped room
+  left_all_rooms        persona left every joined room
+  no_room_memberships   persona has no remaining room memberships
 
 --epoch binds this watcher to one runtime tenure of the persona. Every probe
 reads the persona's current epoch; once it moves, this watcher is speaking for
@@ -303,13 +307,8 @@ try {
     /**
      * A watcher bound to an epoch stops the moment the persona moves on.
      *
-     * The epoch is carried as returned DATA, never as a WHERE predicate. As a
-     * predicate it would simply remove the row, and the two probes read a missing
-     * row very differently: the scoped one reports "the room was deleted or the
-     * membership disappeared", which is a false and actively misleading
-     * diagnosis, while the all-rooms one reads it as an ordinary quiet interval
-     * and never exits at all. Comparing in JS keeps the true reason attached to
-     * the exit.
+     * The epoch is returned as data, never filtered in SQL, so a takeover remains
+     * distinguishable from room and membership state changes.
      */
     const checkEpoch = (current) => {
         if (args.epoch === undefined)
@@ -389,18 +388,32 @@ try {
         };
     }
     else {
-        const present = database
-            .prepare("SELECT 1 FROM memberships WHERE agent_id = ? AND left_at IS NULL LIMIT 1")
+        const membershipCounts = database
+            .prepare(`SELECT COUNT(*) AS total,
+                COALESCE(SUM(CASE WHEN left_at IS NULL THEN 1 ELSE 0 END), 0)
+                  AS present
+         FROM memberships WHERE agent_id = ?`)
             .get(args.agent);
-        if (!present)
-            argumentError(`agent "${args.agent}" is not present in any room`);
-        // ANCHORED on the persona row, not on memberships. The unread test alone
-        // returns ZERO rows on a quiet interval -- the normal case -- so there is no
-        // row to hang an epoch column on. Selecting FROM agents makes the result
-        // exactly one row whenever the persona exists, carrying the epoch every
-        // time and the hit only when there is one. A vanished persona yields no row,
-        // which checkEpoch reads as a dead binding rather than as silence.
+        if (membershipCounts.total === 0) {
+            argumentError(`no_room_memberships: agent "${args.agent}" has no room memberships; ` +
+                "join a room and generate a fresh poller command");
+        }
+        if (membershipCounts.present === 0) {
+            argumentError(`left_all_rooms: agent "${args.agent}" has left every joined room; ` +
+                "rejoin one with join_room and use the new poller command");
+        }
+        // Anchor on the persona so every quiet probe still returns epoch and
+        // membership state. A vanished persona yields no row.
         const statement = database.prepare(`SELECT a.runtime_epoch AS current_epoch,
+              EXISTS (
+                SELECT 1 FROM memberships all_mb
+                WHERE all_mb.agent_id = @agent
+              ) AS has_membership,
+              EXISTS (
+                SELECT 1 FROM memberships present_mb
+                WHERE present_mb.agent_id = @agent
+                  AND present_mb.left_at IS NULL
+              ) AS has_present,
               (SELECT mb.room_id FROM memberships mb
                 WHERE mb.agent_id = @agent AND mb.left_at IS NULL
                   AND EXISTS (
@@ -415,8 +428,21 @@ try {
         const roomName = database.prepare("SELECT name FROM rooms WHERE id = ?");
         probe = () => {
             const row = statement.get(params);
-            checkEpoch(row ? row.current_epoch : null);
-            if (!row || row.room_id === null)
+            if (!row) {
+                checkEpoch(null);
+                return undefined;
+            }
+            checkEpoch(row.current_epoch);
+            if (!row.has_membership) {
+                argumentError(`no_room_memberships: agent "${args.agent}" has no remaining room ` +
+                    "memberships; join a room and generate a fresh poller command");
+            }
+            if (!row.has_present) {
+                argumentError(`left_all_rooms: agent "${args.agent}" left every joined room while ` +
+                    "this watcher was armed; rejoin one with join_room and use the new " +
+                    "poller command");
+            }
+            if (row.room_id === null)
                 return undefined;
             // Name lookup only on a HIT, so the quiet path stays one statement.
             const named = roomName.get(row.room_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multi-agent-collaboration-mcp",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "MCP server: a shared chat room where AI agents coordinate via a SQLite-backed message log",
   "license": "Apache-2.0",
   "repository": {