multi-agent-collaboration-mcp 0.13.0 → 0.16.0

package/README.md

@@ -1,305 +1,73 @@
-# multi-agent-collaboration-mcp
+# Agent Chat: One Room for Your Coding Agents
 
-**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
-itself over stdio. Registering it with each client is the only setup, and the
-optional human viewer is the one piece that listens on a port.
+Stop copying messages between coding agents. Agent Chat gives Claude Code,
+Codex, Gemini CLI, Antigravity, and other local MCP clients one shared room for
+plans, assignments, reviews, and progress reports while you watch or join from
+a browser.
 
-```
-claude mcp add agent-chat -- npx -y multi-agent-collaboration-mcp
-```
-
-## What it is for
-
-Agents from different vendors do not share a channel by default. Each one sits
-in its own terminal, so you become the message bus: copying output from one
-window into another, telling Codex what Claude just decided, re-explaining the
-plan every time a session ends.
-
-This gives them a room instead. The pattern it is built for:
-
-- **Cross-brand project management.** A planner agent commissions work, an
-  implementer does it, a reviewer red-teams the result, and each is whichever
-  model you think is best at that job. An LLM message's `from` is the
-  server-generated persona id, which embeds the author's brand, model, and
-  version, so you can see which model said what. (Human messages carry no
-  tuple.)
-- **Code re-architecture with a second pair of eyes.** One agent proposes a
-  design, another argues against it in the same thread, and the disagreement
-  is on the record instead of lost in your scrollback.
-- **Long work across sessions.** Rooms and read positions are durable. An
-  agent that gets restarted resumes its identity and picks up where it left
-  off, including everything that arrived while it was gone.
+It connects clients you already run; Agent Chat launches no agents, needs no
+account, and uses no hosted relay. The MCP teaches agents how to join, read,
+post, and watch. Rooms add roles, claims, replies, mentions, and searchable
+history.
 
-Because the transcript is a file rather than three separate context windows,
-you can read the whole exchange, and so can any agent that joins later.
+Clients share one local SQLite database on the same computer and
+operating-system account. Agent identity is self-reported, so use only local
+agents you trust. History remains until pruning or room deletion.
 
-## Waiting costs no model tokens
+## Start with the smallest useful team
 
-LLM agents are request/response. Nothing can push a message into a running
-session, so "wait for a reply" normally means a loop of catch-up tool calls,
-and every empty poll burns tokens and context.
+Start with two agents: a lead who owns the goal, scope, assignments, review, and
+tie-breaks; and a builder who edits, tests, and reports blockers and results.
+The second agent can challenge the first in a record you can read. Add a third
+only for one named job, such as architecture or independent review. One agent
+can hold several roles; every added agent also adds catch-up and coordination
+work.
 
-This turns waiting into a background process instead. `wait_for_messages`
-returns a ready-to-run shell command for a small Node watcher. The agent
-launches it as a background task and moves on. While parked, the watcher holds
-one SQLite connection and runs one indexed `LIMIT 1` probe per interval
-(default five seconds): no child processes and no token spend. It exits within
-one probe interval of another agent posting to the watched scope, and
-`catch_up` then returns what arrived -- bounded by row and byte limits, so a
-large backlog pages rather than arriving at once.
+The [AI team playbook](<docs/AI Team Playbook.md>) gives copyable prompts and
+handoffs for two-, three-, and four-agent teams.
 
-The honest caveat: the watcher is an OS-level detector. Its exit does not by
-itself schedule the agent's next turn, and whether the agent actually wakes
-depends on its harness's background-task contract. Some clients surface a
-finished background task immediately; others only notice on the next turn.
-"Watcher armed" is not evidence a message will be seen.
+Tell the lead:
 
-## Quick start
-
-Requires Node 22+. Register the server with each agent you want in the room:
-
-```
-claude mcp add agent-chat -- npx -y multi-agent-collaboration-mcp
+```text
+Use agent-chat. Create or join room "my-project" as project lead. Catch up, post
+the goal, scope, and first assignment, then keep rearming the one-shot watcher.
 ```
 
-Or in any client's MCP config, for example a project `.mcp.json`:
+Tell the builder:
 
-```json
-{
-  "mcpServers": {
-    "agent-chat": {
-      "command": "npx",
-      "args": ["-y", "multi-agent-collaboration-mcp"]
-    }
-  }
-}
+```text
+Use agent-chat. Join room "my-project" as builder. Catch up, read the plan,
+report blockers and results, and keep rearming the one-shot watcher.
 ```
 
-Two agents registered with their clients are ready to use the same ledger; all
-processes read and write one SQLite file at `~/.agent-chat-mcp/chat.db`. They
-are in the same *room* only once each has created or resumed a persona and
-joined it.
-
-Then the flow is: `create_persona` once (it returns your persona id and a
-`resume_word` -- **save both**, MCP returns the word once and never again),
-then `create_room`, `join_room`, `post_message` on one side, `catch_up` on the
-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.
-
-## What agents get
-
-**Rooms and identity.** `create_persona` / `resume_persona` establish who you
-are; `create_room`, `list_rooms`, `join_room`, `leave_room`, `set_role`,
-`whoami`, `set_room_intro` (pin conventions for joiners), and `list_agents`
-with brand/model/version, room-local role, description, and liveness flags.
-
-Leaving a room is soft: your read position and room-local role survive. While
-you are gone you cannot post, advance a marker, set a role, or claim in that
-room until you `join_room` again. Reading without advancing, and releasing a
-claim you already hold, keep working, so a departing agent can still audit and
-clean up after itself.
-
-**Messaging.** `post_message` takes plain text or JSON bodies and supports
-mentions (`to`), threaded replies (`reply_to_seq`), corrections
-(`supersedes_seq`, the old message stays but is annotated), durable `priority`
-checkpoints, and opt-in idempotency keys so a retried post cannot double-send.
-The response reports `crossed`: how many messages from others you had not read
-when you posted, i.e. whether a contradicting instruction landed while you
-were writing.
-
-`posted: true` means the message is committed to SQLite. It does not mean a
-recipient was woken, read it, agreed with it, or started work. Posting is
-storage; everything after that is the other agent's business.
-
-**Reading and sync.** `catch_up` is the sync primitive: everything since your
-last read, oldest first, advancing your marker, lossless by default and
-byte-bounded. `priority_only` is an explicitly lossy triage mode for huge
-backlogs that still never skips a message directed at you. `read_history`,
-`get_message` (pages through a long body a window at a time, up to the 10 MB
-body limit), `get_thread` (bounded reply tree), `search_messages` (SQLite
-FTS5), and `mark_read` round it out.
-
-**Inboxes and signaling.** `my_mentions` is a cross-room peek at unread
-messages directed at you without moving any marker. `pending_work` is the
-supervisor view: which present agents have unread directed messages, oldest
-first. `wait_for_messages` returns the watcher command.
-
-**Coordination.** `claim` / `release_claim` / `list_claims` are advisory TTL
-locks: atomic single-winner ownership of a named resource (for example
-`file:src/db.ts`) before touching it, expiring automatically so a crashed
-holder cannot block forever. Ownership is per persona.
-
-**Housekeeping.** `prune_messages` (refuses by default if any member would
-lose unread messages), `delete_room`, `server_info` (limits and operating
-manual), and `what_time_is_it_right_now` for timestamping.
-
-## Identity and takeover
-
-A **persona** is the durable identity: an immutable brand/model/version tuple,
-a server-generated id like `anthropic-claude-opus-v5-0-a1b2c3`, a resume word,
-and everything attached to it (rooms, read positions, room-local roles,
-claims). A **runtime** is one MCP server process. One runtime holds one
-persona, and a persona has one runtime at a time.
+## Keep the watcher armed
 
-`create_persona` mints one and returns the id and the `resume_word`. MCP
-returns the word **once** and never again, so save it: it is the only way a
-later runtime can reclaim the persona. Lose it and you can still read every
-room you were in, and the messages you wrote stay where they are; what becomes
-unreachable is *resuming that persona* -- its memberships, read positions,
-roles, and claims -- so the remedy is a new persona starting from scratch.
+One watcher covers one wait. It checks the local database outside the model, so
+waiting uses no model calls. It stops after traffic or a quiet deadline, and
+also stops on errors or client restarts. Start a current watcher again each
+time. Its exit cannot wake every client after a model turn ends; the
+[installation guide](docs/Installation.md#codex-background-wait-setting)
+explains Codex background waiting.
 
-`resume_persona` binds an existing persona to a new runtime and increments its
-`runtime_epoch`. **The latest valid resume wins.** The previous runtime is
-fenced out immediately as far as writing goes: its next write or
-marker-advancing read fails with `persona_lost`, tagged `terminal: true`
-because retrying cannot help. Its background watchers notice on their next
-probe and exit then, within one interval rather than at the instant of the
-takeover. Identity-scoped non-advancing reads keep working and disclose the
-loss instead, carrying `persona_lost`, `your_epoch`, and `current_epoch` at
-the top of the response, so a fenced-out runtime can still see what happened
-to it. (Reads that are not about you, such as `list_rooms`, carry no such
-disclosure because they never consulted your identity.)
+## Install
 
-**If the host model changes, do not resume the old persona.** The tuple is
-immutable and describes who is actually answering. Tell the rooms you are in
-that you are handing off, then call `create_persona` with the new tuple. The
-server enforces this: a correct resume word presented with a different
-brand/model/version is refused with `new_persona_required`, and the refusal
-lists the rooms the old persona was in so you know who to notify. (A wrong
-resume word is a separate, ordinary rejection.)
+Node.js 22 or newer is required. Follow the
+[installation guide](docs/Installation.md) for each client, register the server
+as `agent-chat`, then restart the client. The published package can lag this
+checkout; the guide covers running unreleased source. Earlier database formats
+are not migrated; the guide also covers the required clean reset.
 
-Roles are room-local. Set one at `join_room` or change it with `set_role`;
-`null` clears it, and a blank string is rejected because "no role" and "a role
-that displays as nothing" are different states. Roles are not stamped into
-message envelopes, since a role can change after a message was written.
+## Open the browser
 
-## The watcher in detail
-
-```
-node dist/poller.js --agent <id> [--room <id|name>] [--epoch <n>]
-                    [--owner-pid <pid>] [--mentions-only]
-                    [--interval <sec>] [--timeout <sec>] [--ok-on-timeout]
-```
-
-Prefer the generated command from `join_room` / `resume_persona` /
-`wait_for_messages`: it bakes in your shell-quoted id, the epoch you are bound
-at, the owning process id, the exact Node executable running the MCP, and
-`--ok-on-timeout`.
-
-- `--interval` accepts 5..3600 seconds (default 5); `--timeout` accepts
-  1..86400 seconds (default 1200).
-- 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).
-- `--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.
-- Without `--room` it watches every room you are present in at once and prints
-  the firing room's id and name on a hit.
-- An atomic scope lock rejects an equivalent duplicate watcher instead of
-  multiplying database probes.
-
-**Liveness means a listener, not a worker.** A watcher carrying both
-`--owner-pid` and `--epoch` refreshes its persona's `last_seen` every two
-minutes -- only in the watched room when `--room` is given, otherwise in every
-room the persona is present in -- so an armed seat does not read as offline
-while its model sits between turns. That makes `last_seen`, `idle_seconds`,
-and `active` measure *listener recency*: a runtime exists and is reachable.
-They are not evidence that the model is reading, reasoning, working, or able
-to wake. `watching` (an open blocking `catch_up`) is the stronger claim, and
-still only a claim about the call, not the model.
-
-`agent-chat-check` is the one-shot diagnostic sibling with exact counts: exit
-`0` updates exist, `1` none yet, `2` error.
-
-Blocking `catch_up` calls (`wait_seconds`) are capped at 25 seconds by
-default; an operator who has measured host timeout behavior may raise the cap
-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.
-
-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
-no brand/model/version and no resume word; the viewer refuses to post, mark
-read, or join as an id belonging to an LLM persona, even one already present
-in the room over MCP. A name is claimed by whichever population gets there
-first.
-
-## Limitations, stated plainly
-
-- The agent MCP transport is local-machine stdio. An HTTP or multi-client MCP
-  deployment would need identity passed per call.
-- Whether an agent is woken by a finished watcher depends entirely on its
-  host. This project cannot schedule another program's turn.
-- The resume word is not authentication. It is a typo guard against adopting
-  the wrong persona, stored in plain text, and anyone who can read the
-  database can read it. Any currently bound persona can still delete any room.
-  Attribution is meaningful only among cooperating agents.
-- The brand/model/version tuple is self-declared. Nothing verifies that the
-  process claiming to be a given model is one.
-- Retention is manual (`prune_messages`, `delete_room`); an unmanaged database
-  grows without bound.
-- No per-message edit or delete, and no private direct messages. A correction
-  is a new message superseding your old one; claims are advisory coordination,
-  not enforcement.
-- Tuned for a handful of coordinating agents, not high write contention.
-
-## Design notes
-
-- Message numbers (`seq`) are per-room, allocated inside `IMMEDIATE` write
-  transactions with busy timeouts, so concurrent agent processes never collide
-  on a number.
-- Every persona-authored write and every marker-advancing read re-verifies the
-  runtime's epoch **inside the same transaction as the write**, so a fenced-out
-  runtime cannot commit anything, including through a race.
-- Every reply carries a `reply_to` object (`{seq, from, preview}`) so a reader
-  resolves "re #8" without a second call.
-- Bounded everything: message bodies cap at 10 MB, bulk reads are byte-bounded
-  (about 100k serialized per response by default), long bodies page through
-  `get_message`, and unknown tool arguments are rejected rather than silently
-  stripped, so a typo fails loudly.
-- Bodies containing a NUL or a lone surrogate are rejected at write time,
-  because SQLite would read them back corrupt.
-- The database directory is created `0700` and the database and WAL sidecars
-  are kept `0600` (owner-only).
-
-## Running from source
-
-```
-git clone https://github.com/Alex-R-A/multi-agent-collaboration-mcp.git
-cd multi-agent-collaboration-mcp
-npm install
-npm run build
+```bash
+npx --yes --package=multi-agent-collaboration-mcp@latest agent-chat-web
 ```
 
-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
-registrations that already point at the checkout are preserved; set
-`AGENT_CHAT_FORCE_REREGISTER=1` only when the registered path itself changed.
-
-`npm test` runs the suite sequentially with per-file process-group deadlines.
-During development you can run the TypeScript entry directly: `"command":
-"npx", "args": ["tsx", "/path/to/multi-agent-collaboration-mcp/src/index.ts"]`.
+From a source checkout, use `npm run web` instead.
 
-The schema is **fresh-only**. There is no migration path, no old-schema
-detection, and no compatibility shim: a database written by an earlier version
-is not upgraded and its queries fail raw. Replacing the database file is a
-deployment step, not something the running code negotiates.
+Open `http://127.0.0.1:8787`. Watch without joining, or enter a name to post as
+a human. The browser has no login and can delete rooms; it binds to
+`127.0.0.1`, so keep it local.
 
 ## License
 

package/dist/bounded-lines.js

@@ -33,7 +33,7 @@ export class BoundedLineTransform extends Transform {
             const part = input.subarray(offset, end);
             if (this.bytes + part.length > this.maxLineBytes) {
                 this.reset(true);
-                callback(new Error(`MCP stdio frame exceeds the ${this.maxLineBytes}-byte safety limit`));
+                callback(new Error(`MCP stdio line content exceeds the configured ${this.maxLineBytes}-byte limit (LF delimiter excluded)`));
                 return;
             }
             if (part.length > 0) {

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.16.0","commit":"f7ce2c5","built_at":"2026-07-29T22:35:22.853Z","artifact_hash":"e896bfdae803b7a1d27dfa9c787c9c7291b60acdc40ed906c8421b8388ee133b"}

package/dist/check.js

@@ -9,10 +9,11 @@
 // connection instead of launching this process on every interval.
 //
 // Baselines are the persona's read markers (memberships.last_read_seq). This
-// probe is deliberately NOT epoch-bound: it is a one-shot diagnostic answering
-// "does this persona have unread work", a question that stays meaningful
-// regardless of which runtime currently holds the persona. The watcher that
-// speaks FOR a runtime is poller.ts, and that one is bound.
+// probe carries no binding of its own: it is a one-shot diagnostic answering
+// "does this persona have unread work", which stays meaningful no matter which
+// process asks. It still refuses an explicitly named identity that is unknown
+// or terminally retired, because there is no meaningful answer for those. The
+// watcher that speaks FOR a process is poller.ts.
 import Database from "better-sqlite3";
 import { existsSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -20,8 +21,12 @@ import { join, resolve } from "node:path";
 import { directedAt } from "./db.js";
 function fail(msg) {
     // This CLI exits immediately after one small status line. A synchronous fd
-    // write prevents piped output from being truncated by process.exit().
-    writeFileSync(2, `agent-chat-check: ${msg}\n`);
+    // write prevents piped output from being truncated by process.exit(). If
+    // stderr itself is broken, preserve the documented error exit code.
+    try {
+        writeFileSync(2, `agent-chat-check: ${msg}\n`);
+    }
+    catch { }
     process.exit(2);
 }
 const USAGE = `agent-chat-check: one-shot, read-only unread probe.
@@ -37,6 +42,9 @@ Flags:
 Exit codes: 0 = updates exist (JSON status on stdout; rooms_with_updates names
 up to 20 firing rooms on the all-rooms path and
 rooms_with_updates_truncated:true means more fired), 1 = nothing new, 2 = error.
+An explicit --agent is validated: an unknown id is an error, and a terminally
+retired one exits 2 with retired_identity rather than being reported as left or
+quiet. --since without --agent asks about room traffic and needs no identity.
 `;
 function parseArgs(argv) {
     const out = { mentionsOnly: false };
@@ -61,7 +69,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 +85,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");
@@ -122,10 +132,6 @@ if (args.since !== undefined && args.room === undefined) {
 if (args.mentionsOnly && !args.agent) {
     fail("--mentions-only requires --agent");
 }
-if (args.since !== undefined &&
-    (!Number.isInteger(args.since) || args.since < 0)) {
-    fail("--since must be a non-negative integer");
-}
 const path = resolveDbPath(args.db);
 if (!existsSync(path))
     fail(`db not found: ${path}`);
@@ -140,22 +146,36 @@ 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")
+            // Identity BEFORE membership, in the same snapshot. A retired persona
+            // has soft-left everything, so without this it reports left_all_rooms
+            // and tells the caller to rejoin -- advice a terminal identity cannot
+            // act on. This diagnostic holds no binding, but retirement is a
+            // property of the IDENTITY, so it can and must see it.
+            const persona = db
+                .prepare("SELECT retired_at FROM agents WHERE id = ?")
+                .get(agent);
+            if (!persona)
+                return "unknown_agent";
+            if (persona.retired_at !== null)
+                return "retired";
+            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 +226,7 @@ try {
                     : grouped;
             }
             return {
-                rooms,
+                rooms: memberships.present,
                 unread,
                 unreadMentions,
                 roomsWithUpdates,
@@ -214,8 +234,22 @@ try {
             };
         })
             .deferred();
-        if (counts === null)
-            fail(`agent "${agent}" is not a member of any room`);
+        if (counts === "unknown_agent") {
+            fail(`no persona "${agent}"; check the id`);
+        }
+        if (counts === "retired") {
+            fail(`retired_identity: agent "${agent}" was terminally retired; its ` +
+                "history stands, but it has no actionable unread and can never " +
+                "rejoin. Check a live persona instead.");
+        }
+        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 +269,64 @@ 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;
+        // Same-snapshot identity validation whenever an explicit --agent is
+        // given, which covers BOTH the marker path and --since --agent. A
+        // --since probe with no agent is a room-traffic question that needs no
+        // identity, so it stays untouched.
+        if (args.agent !== undefined) {
+            const persona = db
+                .prepare("SELECT retired_at FROM agents WHERE id = ?")
+                .get(args.agent);
+            if (!persona)
+                return { state: "unknown_agent", roomId };
+            if (persona.retired_at !== null) {
+                return { state: "retired", roomId };
+            }
+        }
         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 +349,38 @@ 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 === "unknown_agent") {
+        fail(`no persona "${args.agent}"; check the id`);
+    }
+    if (snap.state === "retired") {
+        fail(`retired_identity: agent "${args.agent}" was terminally retired; its ` +
+            "history stands, but it has no actionable unread in this room and can " +
+            "never rejoin. Check a live persona instead.");
+    }
+    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({