multi-agent-collaboration-mcp 0.12.0 → 0.13.0

package/dist/poller.js

@@ -9,7 +9,7 @@ import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 const USAGE = `agent-chat-poller: wait for unread work with one SQLite probe every five seconds.
 Usage:
-  poller.js --agent <id> [--room <id|name>] [--session <nonce>]
+  poller.js --agent <id> [--room <id|name>] [--epoch <n>]
             [--owner-pid <pid>]
             [--mentions-only] [--interval <seconds>] [--timeout <seconds>]
             [--ok-on-timeout]
@@ -17,7 +17,14 @@ Usage:
 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, or DB error.
+timeout exits 124. Exit 2 = invalid arguments, duplicate watcher, DB error, or
+a stale binding (the persona was resumed by a newer runtime).
+
+--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
+a runtime that no longer holds the persona, so it exits 2 rather than reporting
+traffic to a seat nobody is sitting in. Omit it only for a diagnostic watch
+that should survive a takeover.
 `;
 function argumentError(message) {
     throw new Error(message);
@@ -34,7 +41,7 @@ function parseInteger(value, flag, min, max) {
 function parseArgs(argv) {
     let agent;
     let room;
-    let session;
+    let epoch;
     let ownerPid;
     let db;
     let mentionsOnly = false;
@@ -60,8 +67,9 @@ function parseArgs(argv) {
             agent = take();
         else if (flag === "--room")
             room = take();
-        else if (flag === "--session")
-            session = take();
+        else if (flag === "--epoch") {
+            epoch = parseInteger(take(), flag, 1, Number.MAX_SAFE_INTEGER);
+        }
         else if (flag === "--owner-pid") {
             ownerPid = parseInteger(take(), flag, 1, 2_147_483_647);
         }
@@ -84,7 +92,7 @@ function parseArgs(argv) {
             timeoutOk = true;
         }
         else if (flag === "--since") {
-            argumentError("--since is intentionally unsupported: frozen baselines can re-fire forever; use --session");
+            argumentError("--since is intentionally unsupported: a frozen baseline re-fires forever once crossed; every probe reads the current read marker instead");
         }
         else if (flag === "--help" || flag === "-h") {
             process.stdout.write(USAGE);
@@ -100,12 +108,10 @@ function parseArgs(argv) {
         argumentError("--agent is too long");
     if (room && room.length > 500)
         argumentError("--room is too long");
-    if (session && session.length > 500)
-        argumentError("--session is too long");
     return {
         agent,
         room,
-        session,
+        epoch,
         ownerPid,
         db,
         mentionsOnly,
@@ -168,19 +174,23 @@ function acquireLock(path, token) {
 }
 const sleep = (milliseconds) => new Promise((done) => setTimeout(done, milliseconds));
 async function sleepWhileOwnerAlive(milliseconds, ownerPid) {
-    // Independent/manual pollers need no five-second owner heartbeat; let their
-    // single timer sleep for the requested interval without needless wakeups.
+    // A watcher with no owner has nothing to check for; let its single timer
+    // sleep the whole interval instead of waking every five seconds to ask.
     if (ownerPid === undefined) {
         await sleep(milliseconds);
         return true;
     }
+    // An owned watcher subdivides the interval so it notices a dead owner within
+    // five seconds rather than at the next probe, which may be an hour away. This
+    // is a liveness CHECK of another process, unrelated to the last_seen
+    // heartbeat this watcher writes for its own persona.
     const deadline = Date.now() + milliseconds;
     for (;;) {
         const remaining = deadline - Date.now();
         if (remaining <= 0)
             return true;
         await sleep(Math.min(5_000, remaining));
-        if (ownerPid !== undefined && !processIsAlive(ownerPid))
+        if (!processIsAlive(ownerPid))
             return false;
     }
 }
@@ -234,7 +244,15 @@ try {
     const path = realpathSync(requestedPath);
     database = new Database(path);
     database.pragma("busy_timeout = 2000");
-    database.pragma("query_only = ON");
+    // A GENERATED runtime watcher -- one this server's wait_for_messages handed
+    // out, identified by carrying both --owner-pid and --epoch -- refreshes its
+    // persona's last_seen so an armed seat does not read as offline while the
+    // model is between turns. Nothing else the watcher does may write, and a
+    // watcher without that pair (a hand-run diagnostic watch) stays strictly
+    // read-only.
+    const heartbeatEnabled = args.ownerPid !== undefined && args.epoch !== undefined;
+    if (!heartbeatEnabled)
+        database.pragma("query_only = ON");
     let resolvedRoom;
     if (args.room) {
         const numericRoom = /^\d+$/.test(args.room) && Number.isSafeInteger(Number(args.room));
@@ -248,58 +266,62 @@ try {
         if (!resolvedRoom)
             argumentError(`no room "${args.room}"`);
     }
-    // A global /tmp/agent-chat-pollers directory makes the first OS user its
-    // owner (0700) and prevents every other user from starting a watcher. Use a
-    // per-UID primary directory on POSIX. When this user owns the legacy
-    // directory, acquire the same scoped lock there first as a zero-runtime-cost
-    // rolling-upgrade guard: old and new pollers must not bypass each other's
-    // singleton merely because the lock directory changed.
+    // ONE lock directory, per OS user. A shared /tmp/agent-chat-pollers would make
+    // the first user to create it the 0700 owner and lock every other user out of
+    // running a watcher at all, so POSIX gets a uid suffix. Elsewhere tmpdir() is
+    // already per-user.
     const uid = typeof process.getuid === "function" ? process.getuid() : null;
-    const legacyLockDir = join(tmpdir(), "agent-chat-pollers");
-    try {
-        mkdirSync(legacyLockDir, { recursive: true, mode: 0o700 });
-    }
-    catch (error) {
-        const code = error.code;
-        if (uid === null || !["EACCES", "EPERM", "EEXIST"].includes(code ?? "")) {
-            throw error;
-        }
-    }
-    const legacyStat = lstatSync(legacyLockDir);
-    const lockDirs = [];
-    if (legacyStat.isDirectory() && (uid === null || legacyStat.uid === uid)) {
-        lockDirs.push(legacyLockDir);
-    }
-    else if (uid === null) {
-        argumentError(`watcher lock path is not a directory: ${legacyLockDir}`);
+    const lockDir = join(tmpdir(), uid === null ? "agent-chat-pollers" : `agent-chat-pollers-${uid}`);
+    mkdirSync(lockDir, { recursive: true, mode: 0o700 });
+    const lockStat = lstatSync(lockDir);
+    if (!lockStat.isDirectory()) {
+        argumentError(`watcher lock path is not a directory: ${lockDir}`);
     }
-    if (uid !== null) {
-        const uidLockDir = join(tmpdir(), `agent-chat-pollers-${uid}`);
-        mkdirSync(uidLockDir, { recursive: true, mode: 0o700 });
-        const uidStat = lstatSync(uidLockDir);
-        if (!uidStat.isDirectory() || uidStat.uid !== uid) {
-            argumentError(`watcher lock directory is owned by another user: ${uidLockDir}`);
-        }
-        lockDirs.push(uidLockDir);
+    if (uid !== null && lockStat.uid !== uid) {
+        argumentError(`watcher lock directory is owned by another user: ${lockDir}`);
     }
+    // The epoch is PART of the singleton key. Two watchers of the same persona
+    // and room at different epochs are not duplicates: the older one belongs to a
+    // runtime that has already been fenced out and will exit on its next probe.
+    // Keying without it made a freshly-resumed runtime unable to arm a watcher
+    // until the dying one noticed, leaving the new seat deaf for up to one
+    // interval at exactly the moment it most needed to hear.
     const scopeKey = JSON.stringify([
         path,
         args.agent,
         resolvedRoom?.id ?? null,
-        args.session ?? null,
+        args.epoch ?? null,
         args.mentionsOnly,
     ]);
     const lockName = createHash("sha256").update(scopeKey).digest("hex") + ".lock";
-    for (const lockDir of lockDirs) {
-        const lockPath = join(lockDir, lockName);
-        // Register before acquiring: a signal delivered immediately after the
-        // synchronous create still lets cleanup find the token-owned file.
-        lockPaths.push(lockPath);
-        acquireLock(lockPath, lockToken);
-    }
-    const params = {
-        agent: args.agent,
-        session: args.session ?? "",
+    const lockPath = join(lockDir, lockName);
+    // Register before acquiring: a signal delivered immediately after the
+    // synchronous create still lets cleanup find the token-owned file.
+    lockPaths.push(lockPath);
+    acquireLock(lockPath, lockToken);
+    const params = { agent: args.agent };
+    /**
+     * 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.
+     */
+    const checkEpoch = (current) => {
+        if (args.epoch === undefined)
+            return;
+        if (current === null) {
+            argumentError(`persona "${args.agent}" no longer exists; this watcher's binding is dead`);
+        }
+        if (current !== args.epoch) {
+            argumentError(`stale_binding: persona "${args.agent}" is now at runtime epoch ${current}, ` +
+                `this watcher was bound at ${args.epoch}. A newer runtime holds the ` +
+                `persona; regenerate the poller command from that runtime.`);
+        }
     };
     const directed = args.mentionsOnly
         ? ` AND (g.mentions IS NOT NULL OR g.reply_to_agent IS NOT NULL)
@@ -309,31 +331,58 @@ try {
     let probe;
     if (resolvedRoom) {
         const membership = database
-            .prepare("SELECT 1 FROM memberships WHERE room_id = ? AND agent_id = ?")
+            .prepare("SELECT left_at FROM memberships WHERE room_id = ? AND agent_id = ?")
             .get(resolvedRoom.id, args.agent);
         if (!membership) {
             argumentError(`agent "${args.agent}" has not joined room ${resolvedRoom.id}`);
         }
+        if (membership.left_at !== null) {
+            argumentError(`left_room: agent "${args.agent}" has left room ${resolvedRoom.id}; ` +
+                `a watcher on a room you are absent from would deliver traffic peers ` +
+                `can see you are not receiving. Rejoin with join_room and use the ` +
+                `poller command it returns.`);
+        }
         params.room_id = resolvedRoom.id;
+        // has_updates, current_epoch and left_at are all COLUMNS of a row this
+        // query always returns while the room and membership exist, so "no row"
+        // keeps its single unambiguous meaning.
         const statement = database.prepare(`SELECT r.name AS room_name,
+              (SELECT a.runtime_epoch FROM agents a WHERE a.id = @agent)
+                AS current_epoch,
+              mb.left_at AS left_at,
               EXISTS (
                 SELECT 1 FROM messages g
                 WHERE g.room_id = r.id
-                  AND g.seq > CASE WHEN @session = '' THEN mb.last_read_seq
-                                   ELSE COALESCE(sm.last_read_seq, mb.last_read_seq) END
+                  AND g.seq > mb.last_read_seq
                   AND g.agent_id != @agent${directed}
                 LIMIT 1
               ) AS has_updates
        FROM rooms r
        JOIN memberships mb ON mb.room_id = r.id AND mb.agent_id = @agent
-       LEFT JOIN session_markers sm ON sm.room_id = r.id
-            AND sm.agent_id = mb.agent_id AND sm.session_id = @session
        WHERE r.id = @room_id`);
         probe = () => {
             const row = statement.get(params);
             if (!row) {
                 argumentError(`room ${resolvedRoom.id} was deleted or the membership disappeared while watching`);
             }
+            checkEpoch(row.current_epoch);
+            // Checked on EVERY probe, not just at arm time. A watcher armed while
+            // present and left afterwards kept firing invisibly: peers correctly saw
+            // the persona absent while its watcher still delivered. left_at rides as
+            // returned DATA for the same reason the epoch does -- as a WHERE
+            // predicate it would produce "no row", which already means the room or
+            // membership is gone, and the two need different diagnostics.
+            //
+            // This is a DIFFERENT exit from stale_binding. Both say do not re-arm
+            // this command, but one means another runtime holds the persona and the
+            // other means this persona is not in the room; the next agent should not
+            // have to guess which.
+            if (row.left_at !== null) {
+                argumentError(`left_room: agent "${args.agent}" left room ${resolvedRoom.id} while ` +
+                    `this watcher was armed; it stops rather than deliver traffic to a ` +
+                    `room peers can see you are absent from. Rejoin with join_room and ` +
+                    `use the poller command it returns.`);
+            }
             return row.has_updates
                 ? { room_id: resolvedRoom.id, room_name: row.room_name }
                 : undefined;
@@ -345,33 +394,91 @@ try {
             .get(args.agent);
         if (!present)
             argumentError(`agent "${args.agent}" is not present in any room`);
-        const statement = database.prepare(`SELECT mb.room_id AS room_id, r.name AS room_name
-       FROM memberships mb
-       JOIN rooms r ON r.id = mb.room_id
-       LEFT JOIN session_markers sm ON sm.room_id = mb.room_id
-            AND sm.agent_id = mb.agent_id AND sm.session_id = @session
-       WHERE mb.agent_id = @agent AND mb.left_at IS NULL
-         AND (@session = '' OR NOT EXISTS (
-           SELECT 1 FROM session_presence sp
-           WHERE sp.room_id = mb.room_id AND sp.agent_id = mb.agent_id
-             AND sp.session_id = @session AND sp.left_at IS NOT NULL
-         ))
-         AND EXISTS (
-           SELECT 1 FROM messages g
-           WHERE g.room_id = mb.room_id
-             AND g.seq > CASE WHEN @session = '' THEN mb.last_read_seq
-                              ELSE COALESCE(sm.last_read_seq, mb.last_read_seq) END
-             AND g.agent_id != @agent${directed}
-           LIMIT 1
-         )
-       LIMIT 1`);
-        probe = () => statement.get(params);
+        // 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.
+        const statement = database.prepare(`SELECT a.runtime_epoch AS current_epoch,
+              (SELECT mb.room_id FROM memberships mb
+                WHERE mb.agent_id = @agent AND mb.left_at IS NULL
+                  AND EXISTS (
+                    SELECT 1 FROM messages g
+                    WHERE g.room_id = mb.room_id
+                      AND g.seq > mb.last_read_seq
+                      AND g.agent_id != @agent${directed}
+                    LIMIT 1
+                  )
+                LIMIT 1) AS room_id
+       FROM agents a WHERE a.id = @agent`);
+        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)
+                return undefined;
+            // Name lookup only on a HIT, so the quiet path stays one statement.
+            const named = roomName.get(row.room_id);
+            if (!named)
+                return undefined; // deleted between the two reads
+            return { room_id: row.room_id, room_name: named.name };
+        };
     }
+    /**
+     * Liveness heartbeat for a generated runtime watcher.
+     *
+     * ONE prepared, epoch-fenced UPDATE. The EXISTS clause is the fence: a watcher
+     * whose persona has since been resumed elsewhere matches no row, so a stale
+     * runtime cannot refresh liveness even in the interval before its next probe
+     * notices and exits. It sets last_seen and nothing else -- left_at is never
+     * cleared, so this cannot resurrect a seat that left the room. Failure is
+     * swallowed: a watcher that cannot write must still report traffic.
+     *
+     * Cost is one write per two minutes per armed watcher against five-second
+     * reads. Its contention impact is UNMEASURED.
+     */
+    const HEARTBEAT_INTERVAL_MS = 120_000;
+    // SCOPE MATTERS. A watcher with --room listens to exactly ONE room, so it may
+    // only refresh THAT room. Refreshing every present membership from a scoped
+    // watcher tells peers in rooms nobody is watching that this persona is
+    // listening there, which is the same false availability the rest of this
+    // work exists to remove. An unscoped watcher does watch every present room,
+    // so it refreshes them all.
+    const heartbeatScope = resolvedRoom ? " AND room_id = @room_id" : "";
+    const heartbeatStatement = heartbeatEnabled
+        ? database.prepare(`UPDATE memberships SET last_seen = datetime('now')
+          WHERE agent_id = @agent AND left_at IS NULL${heartbeatScope}
+            AND EXISTS (SELECT 1 FROM agents a
+                         WHERE a.id = @agent AND a.runtime_epoch = @epoch)`)
+        : null;
+    let lastHeartbeatMs = 0;
+    const heartbeat = () => {
+        if (!heartbeatStatement)
+            return;
+        const now = Date.now();
+        if (lastHeartbeatMs !== 0 && now - lastHeartbeatMs < HEARTBEAT_INTERVAL_MS) {
+            return;
+        }
+        // Stamp before running, so a failing write throttles like a succeeding one
+        // instead of retrying every probe.
+        lastHeartbeatMs = now;
+        try {
+            heartbeatStatement.run({
+                agent: args.agent,
+                epoch: args.epoch,
+                ...(resolvedRoom ? { room_id: resolvedRoom.id } : {}),
+            });
+        }
+        catch { }
+    };
+    heartbeat();
     const deadline = Date.now() + args.timeoutSeconds * 1000;
     for (;;) {
         if (args.ownerPid !== undefined && !processIsAlive(args.ownerPid)) {
             argumentError(`owner MCP process ${args.ownerPid} has ended; regenerate the poller command`);
         }
+        heartbeat();
         // Probe before deciding that the deadline is quiet. The final sleep lands
         // on the deadline; checking time first discarded messages that arrived
         // during that last interval and reported a false timeout.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multi-agent-collaboration-mcp",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "MCP server: a shared chat room where AI agents coordinate via a SQLite-backed message log",
   "license": "Apache-2.0",
   "repository": {
@@ -12,7 +12,6 @@
   "type": "module",
   "bin": {
     "multi-agent-collaboration-mcp": "dist/index.js",
-    "agent-chat-mcp": "dist/index.js",
     "agent-chat-check": "dist/check.js",
     "agent-chat-poller": "dist/poller.js"
   },
@@ -30,9 +29,7 @@
     "web": "node web/server.mjs",
     "prepare": "node scripts/prepare.mjs",
     "pretest": "node scripts/prepare.mjs",
-    "test": "node test/run-suite.mjs",
-    "pretest:concurrency": "node scripts/prepare.mjs",
-    "test:concurrency": "node test/concurrent-catchup.mjs"
+    "test": "node test/run-suite.mjs"
   },
   "engines": {
     "node": ">=22"

package/scripts/stamp-build.mjs

@@ -33,8 +33,10 @@ try {
 
 // A timestamp alone makes every no-change rebuild tell already-running MCP
 // processes they are stale. Hash the executable JS instead: reconnect only
-// when the deployed behavior actually differs. Keep the timestamp for human
-// diagnostics and as a compatibility fallback for stamps made by old builds.
+// when the deployed behavior actually differs. built_at is kept for human
+// diagnostics and ordering ONLY -- it is never compared to decide staleness,
+// and there is no fallback for a stamp without a hash: every stamp this script
+// writes carries one.
 const dist = join(root, "dist");
 const files = [];
 const walk = (dir) => {

package/web/index.html

@@ -1334,29 +1334,12 @@
       // identity and room mapping naming different names; and a ghost
       // sweep's in-flight leave could evict a membership another tab had
       // just re-adopted. Web Locks serialize the whole sequence (awaited
-      // server calls included) across same-origin tabs. localhost is a
-      // secure context, so navigator.locks exists everywhere this runs; the
-      // fallback keeps a degraded single-tab-correct behavior just in case.
-      // Tab-local serialization fallback: a promise chain so that even without
-      // Web Locks (older engines; localhost is a secure context so this is
-      // rare) two membership mutations in the SAME tab cannot interleave their
-      // read-modify-write. It does NOT coordinate across tabs -- only Web Locks
-      // do that -- but it removes the within-tab race the old
-      // Promise.resolve().then(fn) left open.
-      let membershipChain = Promise.resolve();
+      // server calls included) across same-origin tabs. localhost is a secure
+      // context, so navigator.locks exists in every engine this viewer runs
+      // in; there is no fallback path, because a same-tab-only fallback would
+      // silently drop the cross-tab guarantee this exists to provide.
       function withMembershipLock(fn) {
-        if (navigator.locks && navigator.locks.request) {
-          return navigator.locks.request("agent-chat.membership", fn);
-        }
-        // membershipChain always fulfills (swallowed below), so fn runs once.
-        const run = membershipChain.then(() => fn());
-        // Keep the chain alive regardless of fn's outcome; swallow here so a
-        // rejection does not poison every later mutation.
-        membershipChain = run.then(
-          () => undefined,
-          () => undefined,
-        );
-        return run;
+        return navigator.locks.request("agent-chat.membership", fn);
       }
 
       // Memberships whose soft-leave failed (e.g. server briefly down during
@@ -1566,9 +1549,14 @@
       }
 
       function label(m) {
-        // Humans have no role and type 'human'; their name IS the identity.
-        if (m.type === "human") return m.from;
-        return m.role || m.type || m.from;
+        // A human's name IS the identity. An LLM persona shows its MODEL, which
+        // the schema requires for every LLM row, so there is nothing to fall
+        // back to: a blank label would mean a row the schema says cannot exist,
+        // and quietly substituting the brand or the id would hide that. Its
+        // ROLE is deliberately not used here, because roles are room-local and
+        // mutable, so labelling an old message with the current role
+        // misreports who wrote it.
+        return m.is_human ? m.from : m.model;
       }
 
       // Append text with http(s) URLs as clickable links. Everything goes in
@@ -1598,15 +1586,10 @@
         const me = identity();
         if (!me || m.from === me) return false;
         if (Array.isArray(m.mentions) && m.mentions.includes(me)) return true;
-        // The stored reply author decides (it survives parent pruning and
-        // needs no parent row loaded); the in-memory parent lookup remains
-        // as a fallback for rows written before the column existed.
-        if (m.reply_to_agent) return m.reply_to_agent === me;
-        if (m.reply_to_seq) {
-          const parent = state.msgs.find((x) => x.seq === m.reply_to_seq);
-          if (parent && parent.from === me) return true;
-        }
-        return false;
+        // The stored reply author decides it outright: it survives parent
+        // pruning and needs no parent row loaded. Both current writers stamp
+        // it, so a reply with no reply_to_agent is simply not directed.
+        return m.reply_to_agent === me;
       }
 
       async function fetchJson(url) {
@@ -1903,11 +1886,8 @@
           // rendered text is not mistaken for the whole message.
           const note = document.createElement("div");
           note.className = "trunc-note";
-          // body_length is exact (same UTF-16 unit as body.length) when the
-          // row carries a stamped length; rows from old builds fall back to
-          // a codepoint count, which can undershoot the shown length for
-          // astral-heavy text. Guard against emitting an impossible
-          // "showing X of fewer-than-X" notice in that case.
+          // body_length is exact and in the same UTF-16 unit as body.length,
+          // so the comparison below is apples to apples.
           const shown = m.body.length;
           const total = Number(m.body_length);
           note.textContent =