multi-agent-collaboration-mcp 0.16.0 → 0.17.0

package/README.md

@@ -26,6 +26,12 @@ work.
 The [AI team playbook](<docs/AI Team Playbook.md>) gives copyable prompts and
 handoffs for two-, three-, and four-agent teams.
 
+For larger or higher-risk teams, paste the
+[multi-model project-management operating guide](<docs/Multi-Model AI Project Management Operating Guide.md>)
+into the PM LLM's standing context. It defines a model-neutral PM role and
+concrete rules for evidence, authority, assignments, ownership, review,
+verification, and handoff.
+
 Tell the lead:
 
 ```text

package/dist/build-info.json

@@ -1 +1 @@
-{"version":"0.16.0","commit":"f7ce2c5","built_at":"2026-07-29T22:35:22.853Z","artifact_hash":"e896bfdae803b7a1d27dfa9c787c9c7291b60acdc40ed906c8421b8388ee133b"}
+{"version":"0.17.0","commit":"e51920e","built_at":"2026-08-02T07:33:05.580Z","artifact_hash":"f1d5be7bb3ff1b80303165848d201ec8938187d9d97a68ab6257d751a1a437b9"}

package/dist/db.js

@@ -32,11 +32,19 @@ export const MAX_CROSSED_PREVIEW_CHARS = 2_000;
 /** Public MCP/store caps used to keep direct callers from bypassing bounded
  * reads with values the tool schemas would reject. */
 const MAX_BULK_RESULT_CHARS = 400_000;
-const MAX_CATCH_UP_ROWS = 500;
+const MIN_NONADVANCING_RESULT_CHARS = 1_000;
+const MAX_BULK_READ_ROWS = 500;
 const MAX_GET_MESSAGE_CHARS = 400_000;
+const MAX_RECIPIENT_IDS = 100;
 /** Caller-supplied post idempotency keys are opaque, room/author scoped, and
  * intentionally small enough to keep the sparse unique index cheap. */
 export const MAX_CLIENT_MESSAGE_ID_CHARS = 200;
+function requireIntegerInRange(value, name, min, max) {
+    if (!Number.isSafeInteger(value) || value < min || value > max) {
+        throw new Error(`${name} must be an integer from ${min} to ${max}`);
+    }
+    return value;
+}
 /** Persona/human id cap. Exported because the server SIZES the canonical id it
  * generates against it before allocating, rather than discovering the overflow
  * as a store assertion after the fact. */
@@ -1003,6 +1011,7 @@ export class ChatStore {
     listRooms(limit = 200, afterId = 0) {
         const PREVIEW = 300;
         const lim = Math.max(1, Math.floor(limit));
+        const cursor = requireIntegerInRange(afterId, "list_rooms after_id", 0, Number.MAX_SAFE_INTEGER);
         // Rows and total in ONE deferred snapshot: read as separate statements, a
         // concurrent create_room/delete_room BETWEEN them yields an internally
         // contradictory page (e.g. total:4 with no next_id, so the keyset pager
@@ -1024,7 +1033,7 @@ export class ChatStore {
                     (SELECT created_at FROM messages g
                       WHERE g.room_id = r.id ORDER BY g.seq DESC LIMIT 1) AS last_activity
              FROM rooms r WHERE r.id > ? ORDER BY r.id LIMIT ?`)
-                .all(Math.max(0, Math.floor(afterId)), lim + 1);
+                .all(cursor, lim + 1);
             const { c: total } = this.db
                 .prepare("SELECT COUNT(*) AS c FROM rooms")
                 .get();
@@ -1399,6 +1408,9 @@ export class ChatStore {
     retiredIds(ids) {
         if (ids.length === 0)
             return new Set();
+        if (ids.length > MAX_RECIPIENT_IDS) {
+            throw new Error(`retired_ids accepts at most ${MAX_RECIPIENT_IDS} ids`);
+        }
         const placeholders = ids.map(() => "?").join(",");
         const rows = this.db
             .prepare(`SELECT id FROM agents
@@ -1687,9 +1699,9 @@ export class ChatStore {
         // rejoins (INSERT OR IGNORE keeps the row); rows come back in join order.
         let keyset = "";
         const rowParams = { ...base, lim: lim + 1 };
-        if (after !== undefined && Number.isFinite(after)) {
+        if (after !== undefined) {
             keyset = ` AND m.rowid > @after`;
-            rowParams.after = Math.floor(after);
+            rowParams.after = requireIntegerInRange(after, "list_agents after", 0, Number.MAX_SAFE_INTEGER);
         }
         // Rows and count in ONE deferred snapshot so total cannot disagree with the
         // page (parity with listRooms). Fetch one MORE than asked to detect a page.
@@ -2338,6 +2350,9 @@ export class ChatStore {
     recipientStatus(roomId, ids, activeWithinMinutes) {
         if (ids.length === 0)
             return [];
+        if (ids.length > MAX_RECIPIENT_IDS) {
+            throw new Error(`recipient_status accepts at most ${MAX_RECIPIENT_IDS} ids`);
+        }
         const placeholders = ids.map(() => "?").join(",");
         // marker_behind baseline. Read alongside the rows without a transaction:
         // this is a liveness heuristic, not an invariant, and the method already
@@ -2498,13 +2513,14 @@ export class ChatStore {
      * delivered over budget. Oversized bodies arrive truncated with markers;
      * page them via get_message.
      */
-    getThread(roomId, seq, maxDepth = 3, previewChars) {
+    getThread(roomId, seq, maxDepth = 3, previewChars, maxBytes = DEFAULT_MAX_BYTES) {
+        maxBytes = requireIntegerInRange(maxBytes, "get_thread max_bytes", MIN_NONADVANCING_RESULT_CHARS, DEFAULT_MAX_BYTES);
         const tx = this.db.transaction(() => {
-            const focalRow = this.getRawMessage(roomId, seq);
+            const focalRow = this.getRawMessage(roomId, seq, maxBytes);
             if (!focalRow)
                 return undefined;
             const mapPlain = (r, pc) => this.rowToMessage(r, pc);
-            const budget = DEFAULT_MAX_BYTES - THREAD_ENVELOPE;
+            const budget = maxBytes - THREAD_ENVELOPE;
             // Reserve the parent's slot before spending on the focal message: a stub
             // allowance when a parent exists, 4 chars of literal null otherwise. The
             // trailing 2 covers an empty replies array.
@@ -2514,7 +2530,7 @@ export class ChatStore {
             let remaining = budget - JSON.stringify(message).length;
             let parent = null;
             if (parentSeq !== null) {
-                const parentRow = this.getRawMessage(roomId, parentSeq);
+                const parentRow = this.getRawMessage(roomId, parentSeq, maxBytes);
                 if (parentRow) {
                     // Leave a stub allowance (plus array brackets) for the replies when
                     // more than that remains; otherwise the parent gets a stub itself.
@@ -2544,7 +2560,7 @@ export class ChatStore {
               ORDER BY path
               LIMIT @lim
            )
-           SELECT ${messageCols(DEFAULT_MAX_BYTES)}, d.depth AS depth
+           SELECT ${messageCols(maxBytes)}, d.depth AS depth
              FROM descendants d
              CROSS JOIN messages g
              LEFT JOIN messages p ON p.room_id = g.room_id AND p.seq = g.reply_to_seq
@@ -2705,7 +2721,7 @@ export class ChatStore {
         if (!Number.isFinite(limit)) {
             throw new Error("catch_up limit must be finite");
         }
-        const pageLimit = Math.min(MAX_CATCH_UP_ROWS, Math.max(1, Math.floor(limit)));
+        const pageLimit = Math.min(MAX_BULK_READ_ROWS, Math.max(1, Math.floor(limit)));
         // Advancing path: read the cursor, fetch, and advance inside one IMMEDIATE
         // transaction. A deferred WAL transaction could let another writer commit
         // after this read snapshot, then fail the cursor update with
@@ -2856,6 +2872,9 @@ export class ChatStore {
      * snapshot.
      */
     myMentions(agentId, limit, previewChars, maxBytes = DEFAULT_MAX_BYTES, afterId = 0) {
+        limit = requireIntegerInRange(limit, "my_mentions limit", 1, MAX_BULK_READ_ROWS);
+        maxBytes = requireIntegerInRange(maxBytes, "my_mentions max_bytes", MIN_CATCH_UP_RESULT_BUDGET, MAX_BULK_RESULT_CHARS);
+        afterId = requireIntegerInRange(afterId, "my_mentions after_id", 0, Number.MAX_SAFE_INTEGER);
         const tx = this.db.transaction(() => {
             // Fetch ONE more than `limit` so a page cut by the ROW limit (not the
             // byte budget) is detectable. Without the probe, my_mentions was the only
@@ -2939,6 +2958,11 @@ export class ChatStore {
      * `limit`; else older than beforeSeq.
      */
     readHistory(roomId, limit, beforeSeq, previewChars, maxBytes = DEFAULT_MAX_BYTES) {
+        limit = requireIntegerInRange(limit, "read_history limit", 1, MAX_BULK_READ_ROWS);
+        maxBytes = requireIntegerInRange(maxBytes, "read_history max_bytes", MIN_CATCH_UP_RESULT_BUDGET, MAX_BULK_RESULT_CHARS);
+        if (beforeSeq !== undefined) {
+            requireIntegerInRange(beforeSeq, "read_history before_seq", 1, Number.MAX_SAFE_INTEGER);
+        }
         const conds = ["g.room_id = ?"];
         const params = [roomId];
         if (beforeSeq !== undefined) {
@@ -2978,6 +3002,9 @@ export class ChatStore {
      * Returns the previous and new marker plus the room's latest seq.
      */
     markRead(roomId, agentId, seq) {
+        if (seq !== undefined) {
+            requireIntegerInRange(seq, "mark_read seq", 0, Number.MAX_SAFE_INTEGER);
+        }
         const tx = this.db.transaction(() => {
             this.requireLive(agentId);
             // Advancing a marker requires presence and reports the prior cursor.
@@ -3006,21 +3033,22 @@ export class ChatStore {
      * relevance sort can avoid; callers wanting exactly-once delivery should page
      * in one burst.
      */
-    searchMessages(roomId, query, limit, offset = 0) {
+    searchMessages(roomId, query, limit, offset = 0, maxBytes = DEFAULT_MAX_BYTES) {
+        maxBytes = requireIntegerInRange(maxBytes, "search_messages max_bytes", MIN_NONADVANCING_RESULT_CHARS, DEFAULT_MAX_BYTES);
         const off = Math.max(0, Math.floor(offset));
         // Fetch one MORE than asked: a full `limit` page does not by itself prove
         // more exist, so the extra row is the definitive "there is a next page"
         // probe (a page of exactly `limit` matches used to emit a false
         // next_offset that returned nothing).
-        const { rows, exhausted } = this.fetchBounded(this.db.prepare(`SELECT ${messageCols(DEFAULT_MAX_BYTES)}
+        const { rows, exhausted } = this.fetchBounded(this.db.prepare(`SELECT ${messageCols(maxBytes)}
          FROM messages_fts f
          JOIN messages g ON g.id = f.rowid
          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);
+         ORDER BY rank, g.id LIMIT ? OFFSET ?`), [query, roomId, limit + 1, off], maxBytes);
         const hasExtra = rows.length > limit;
         const page = hasExtra ? rows.slice(0, limit) : rows;
-        const { messages, byteLimited } = this.boundByBytes(page, undefined, DEFAULT_MAX_BYTES - SEARCH_ENVELOPE, (r, pc) => this.rowToMessage(r, pc));
+        const { messages, byteLimited } = this.boundByBytes(page, undefined, maxBytes - SEARCH_ENVELOPE, (r, pc) => this.rowToMessage(r, pc));
         // More remain if the byte bound cut the page, a genuine extra match exists
         // beyond `limit`, OR fetchBounded stopped on the raw byte budget with
         // matches unfetched (!exhausted) -- the last case is invisible to

package/dist/index.js

@@ -120,7 +120,7 @@ SIZE AND PAGING
 
 POSTING
 - crossed counts ALL unread from others past your marker at post time (old backlog included, not only mid-composition arrivals); crossed_directed says how many are aimed at you; crossed_range gives the seq span. If crossed > 0, catch_up before acting on replies. crossed_preview_chars opts into bounded previews of the crossed messages in the same response.
-- Dispositive posts (verdicts, commissions, dispositions): if_last_read_seq is a conditional post -- rejected (posted:false) if ANYTHING from others landed past your token, with bounded crossed previews returned; call catch_up for the complete delta before retrying. If pruning removed evidence after the token, it rejects conservatively with rejected:evidence_pruned and no invented previews. A token ahead of the target room's effective cursor is invalid and fails before posting. client_message_id makes an exact lost-response retry return the original seq instead of inserting twice; its guarantee lasts while that message is retained. Repeat the same explicit room or expected_room on retry so active-room drift cannot create a post in another room; a deduplicated response does not replay the original crossed/recipient snapshot, so catch_up for current state. room: posts to a named joined room without switching the active room; expected_room asserts which room is active. Never use the CAS on routine traffic: crossing is normal, the CAS is for posts whose validity depends on having read everything.
+- Use if_last_read_seq for a directive, assignment, or verdict whose validity depends on no peer message arriving after your last catch_up. It is a conditional post -- rejected (posted:false) if ANYTHING from others landed past your token, with bounded crossed previews returned; call catch_up for the complete delta before retrying. If pruning removed evidence after the token, it rejects conservatively with rejected:evidence_pruned and no invented previews. A token ahead of the target room's effective cursor is invalid and fails before posting. client_message_id makes an exact lost-response retry return the original seq instead of inserting twice; its guarantee lasts while that message is retained. Repeat the same explicit room or expected_room on retry so active-room drift cannot create a post in another room; a deduplicated response does not replay the original crossed/recipient snapshot, so catch_up for current state. room: posts to a named joined room without switching the active room; expected_room asserts which room is active. Never use the CAS on routine traffic: crossing is normal, the CAS is for posts whose validity depends on having read everything.
 - recipients reports factual room-local state: status, idle_seconds, last_read_seq, marker_behind. A new unread tag normally adds one to marker_behind. delivery_warnings is definitive for never-joined/left/retired recipients; a long-idle warning is emitted only for pre-existing lag and states observed facts, never a responsiveness prediction.
 - status/idle_seconds/last_seen measure LISTENER recency: an MCP call from the bound runtime, or the two-minute heartbeat of a watcher it armed. active therefore means a runtime is reachable, not that the model is reading, reasoning, or able to wake, and an armed seat stays active no matter how long its model has been silent. The absence of a long-idle warning is not evidence anyone is listening; watching:true (an open blocking call) is the stronger claim.
 - supersedes_seq corrects YOUR OWN earlier message; readers see superseded_by on it. reply_to_seq threads; the log stays flat and globally ordered.
@@ -143,7 +143,7 @@ IDENTITY
 - Human web participants use the reserved 'human-' prefix with a numeric ordinal (human-alex-1). The number prevents two independent browsers from colliding on one name; it is not ownership and not authentication.
 
 BACKGROUND POLLER
-- Run the command returned by join_room or wait_for_messages as a BACKGROUND task. Before arming, call catch_up until remaining is 0 or stops falling. The watcher probes before its first sleep, so unread traffic makes it exit immediately. 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, a live-PID watcher lock, retired_identity, 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>, --owner-pid <pid>. Your own posts never wake it.
+- Launch the command returned by join_room or wait_for_messages as the tracked BACKGROUND task. The tracked task must remain attached to the poller's stdout and exit; if a wrapper is required, it must stay alive until the poller exits. Before arming, call catch_up until remaining is 0 or stops falling. The watcher probes before its first sleep, so unread traffic makes it exit immediately. 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, a live-PID watcher lock, retired_identity, 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>, --owner-pid <pid>. Your own posts never wake it.
 - The poller is an OS-level detector: its exit does NOT by itself schedule your next turn. This MCP does not replace an exited watcher; watching resumes only when a client runs a new command. 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
@@ -1077,8 +1077,11 @@ server.registerTool("join_room", {
             // persona (see the server instructions).
             poller_cmd: pollerCmd(agentId),
             next: "call catch_up until it returns `remaining: 0` or the value stops " +
-                "falling; then run poller_cmd as a background task before starting " +
-                "work. The watcher checks immediately, so unread traffic makes it " +
+                "falling; then launch poller_cmd as the client's tracked background " +
+                "task before starting work. The tracked task must remain attached to " +
+                "the poller's stdout and exit; any wrapper must stay alive until the " +
+                "poller exits. The watcher checks " +
+                "immediately, so unread traffic makes it " +
                 "exit immediately. This MCP server returns the command but cannot " +
                 "launch it.",
             presence_note: "active = recent MCP or poller contact, or a live blocking wait. " +
@@ -1292,8 +1295,9 @@ server.registerTool("post_message", {
         "insert. `posted:true` means committed to SQLite only, not that a " +
         "recipient was woken, acknowledged, or began processing it. A " +
         "deduplicated retry returns the original seq/key only; catch " +
-        "up for current state. For a " +
-        "dispositive post, use `if_last_read_seq` + `expected_room`; use " +
+        "up for current state. For a directive, assignment, or verdict that " +
+        "would be invalid if peer traffic arrived after your last catch_up, use " +
+        "`if_last_read_seq` + `expected_room`; use " +
         "`client_message_id` to deduplicate an exact lost-response retry. " +
         "`crossed_preview_chars` max is 2000. `priority:true` survives explicit " +
         "priority-only backlog triage; `supersedes_seq` corrects your own post.",
@@ -1379,9 +1383,11 @@ server.registerTool("post_message", {
             .int()
             .nonnegative()
             .optional()
-            .describe("Conditional post (CAS) for dispositive messages: reject if ANY " +
-            "message from others carries a seq above this (use your last " +
-            "catch_up's new_last_read_seq). A token ahead of this room's " +
+            .describe("Conditional post (CAS) for a directive, assignment, or verdict " +
+            "that would be invalid if peer traffic arrived after your last " +
+            "catch_up: reject if ANY message from others carries a seq above " +
+            "this (use your last catch_up's new_last_read_seq). A token ahead " +
+            "of this room's " +
             "effective read cursor is invalid and rejected before posting. " +
             "A stale rejection returns posted:false with bounded crossed " +
             "previews; call catch_up for the full delta, then re-send the " +
@@ -1709,6 +1715,8 @@ server.registerTool("catch_up", {
             first = advancingRead(waitSeconds === 0);
         }
         catch (e) {
+            if (e instanceof PersonaLostError)
+                throw e;
             if (!store.getRoom(roomId))
                 return roomDeletedResult();
             throw e;
@@ -1771,6 +1779,8 @@ server.registerTool("catch_up", {
                     hit = advancingRead(false);
                 }
                 catch (e) {
+                    if (e instanceof PersonaLostError)
+                        throw e;
                     if (!store.getRoom(roomId))
                         return roomDeletedResult(true);
                     throw e;
@@ -1790,6 +1800,8 @@ server.registerTool("catch_up", {
                 last = advancingRead(true);
             }
             catch (e) {
+                if (e instanceof PersonaLostError)
+                    throw e;
                 if (!store.getRoom(roomId))
                     return roomDeletedResult(true);
                 throw e;
@@ -2026,7 +2038,9 @@ server.registerTool("wait_for_messages", {
         return ok({
             command,
             run_as: "background process (do not wait for it inline)",
-            how_to: "Run `command` in the background. On exit 0, parse stdout: " +
+            how_to: "Launch `command` as your client's tracked background task. The " +
+                "tracked task must remain attached to the poller's stdout and exit; " +
+                "any wrapper must stay alive until the poller exits. 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, or a " +
                 "terminal room/binding state; inspect stderr before re-arming. The " +
@@ -2209,11 +2223,12 @@ server.registerTool("get_thread", {
         touchSession();
         const { agentId, roomId, roomName } = resolveJoinedRoom(room);
         touchCapturedRoom(roomId, agentId);
-        const thread = store.getThread(roomId, seq, max_depth ?? 3, preview_chars);
+        const lost = lossDisclosure(agentId);
+        const thread = store.getThread(roomId, seq, max_depth ?? 3, preview_chars, DEFAULT_MAX_BYTES - disclosureReserve(lost));
         if (!thread) {
             return fail(`no message ${seq} in room "${roomName}"`);
         }
-        return ok({ ...lossDisclosure(agentId), ...thread });
+        return ok({ ...lost, ...thread });
     }
     catch (e) {
         return failFrom(e);
@@ -2269,9 +2284,10 @@ server.registerTool("search_messages", {
     try {
         touchSession();
         const { agentId, roomId } = requireActive();
+        const lost = lossDisclosure(agentId);
         return ok({
-            ...lossDisclosure(agentId),
-            ...store.searchMessages(roomId, query, limit ?? 20, offset ?? 0),
+            ...lost,
+            ...store.searchMessages(roomId, query, limit ?? 20, offset ?? 0, DEFAULT_MAX_BYTES - disclosureReserve(lost)),
         });
     }
     catch (e) {

package/dist/poller.js

@@ -134,6 +134,9 @@ function dbPath(override) {
     return join(homedir(), ".agent-chat-mcp", "chat.db");
 }
 function processIsAlive(pid) {
+    // Existence only, not process identity. A recycled PID is indistinguishable
+    // here from the process that originally owned it; closing that portability
+    // gap requires a process-instance protocol rather than another PID check.
     if (!Number.isSafeInteger(pid) || pid < 1)
         return false;
     try {
@@ -144,6 +147,8 @@ function processIsAlive(pid) {
         return error.code !== "ESRCH";
     }
 }
+const LOCK_METADATA_READ_ATTEMPTS = 5;
+const LOCK_METADATA_RETRY_DELAY_MS = 25;
 function acquireLock(path, token) {
     try {
         const fd = openSync(path, "wx", 0o600);
@@ -164,11 +169,34 @@ function acquireLock(path, token) {
     catch (error) {
         if (error.code !== "EEXIST")
             throw error;
-        let owner = 0;
-        try {
-            owner = Number(JSON.parse(readFileSync(path, "utf8")).pid);
+        let owner;
+        const retrySignal = new Int32Array(new SharedArrayBuffer(4));
+        for (let attempt = 0; attempt < LOCK_METADATA_READ_ATTEMPTS; attempt++) {
+            try {
+                const metadata = JSON.parse(readFileSync(path, "utf8"));
+                if (typeof metadata.pid === "number" &&
+                    Number.isSafeInteger(metadata.pid) &&
+                    metadata.pid > 0 &&
+                    typeof metadata.token === "string" &&
+                    metadata.token.length > 0) {
+                    owner = metadata.pid;
+                    break;
+                }
+            }
+            catch { }
+            if (attempt + 1 < LOCK_METADATA_READ_ATTEMPTS) {
+                Atomics.wait(retrySignal, 0, 0, LOCK_METADATA_RETRY_DELAY_MS);
+            }
+        }
+        if (owner === undefined) {
+            // The exclusive create publishes the pathname before the tiny metadata
+            // write completes. Give that bounded publication window time to settle,
+            // then preserve exclusion without falsely calling an invalid lock stale.
+            argumentError(`watcher lock metadata could not be read or validated; the lock may be ` +
+                `initializing or stale, so acquisition is refused (lock: ${path}). ` +
+                `Retry without removing it; inspect this exact lock before any manual ` +
+                `recovery`);
         }
-        catch { }
         if (processIsAlive(owner)) {
             argumentError(`watcher lock references live pid ${owner}; refusing a duplicate (lock: ${path})`);
         }

package/docs/AI Team Playbook.md

@@ -0,0 +1,152 @@
+# AI Team Playbook
+
+Use this guide after installing Agent Chat. It is for people who want several
+coding agents to produce one project without becoming the message carrier.
+Start with two seats. Add a seat only when you can name its job in one sentence.
+Agent identity is self-reported, so use only clients you trust.
+
+## Choose the smallest team
+
+| Seats | Roles | Use when |
+| --- | --- | --- |
+| Two | Project lead and builder | Recommended default: one owns the result and one implements it. |
+| Three | Add an architect or reviewer | A named design question, subsystem, or independent review needs its own attention. |
+| Four | Add an oversight reviewer | A long, high-risk, or policy-bound project needs an independent scope and progress check. |
+
+Roles are jobs, not headcount; one agent can hold several. Every added seat must
+catch up, keep its watcher armed, avoid conflicting edits, and report back. Add
+a security, database, performance, or test specialist only for a named problem,
+then remove that seat when the problem is closed.
+
+The project lead is the PM and final tie-breaker. Use your strongest overall
+reasoning model in that seat: it must understand both architecture and
+implementation reports, reject drift, and decide. That is not automatically the
+best code writer. A narrow technical problem may still need your strongest
+specialist as architect.
+
+## Give each role a boundary
+
+| Role | Owns | Does not own |
+| --- | --- | --- |
+| Project lead | Goal, scope, assignments, decisions, review, and completion | Unapproved changes to the human's goal or policy |
+| Builder | Code, tests, file or task claims, and concrete progress reports | Project-wide scope changes |
+| Architect or reviewer | Minimal design, alternatives, risks, and independent review | Editing the work while claiming to review it independently |
+| Oversight reviewer | Plan compliance, policy, elapsed time, stalled work, and unsupported reports | Code correctness or technical review |
+
+The oversight reviewer is the optional global manager. It reports concerns to
+the PM and human, not competing orders to the builder. It can verify observable
+state, but a silent agent may be working, throttled, disconnected, or gone.
+Silence alone proves none of those.
+
+## Start the room
+
+Replace `<room>` and the bracketed project details, then give each prompt to the
+matching agent.
+
+Open the local browser page beside the agent terminals. You can watch without
+joining; enter a name only when you want to post, answer, or break a tie.
+
+Project lead:
+
+```text
+Use agent-chat. Create or join room "<room>" as project lead. Catch up, then post
+the goal, required constraints, non-goals, and definition of done. Assign
+bounded work, check claims and progress, resolve disagreements, reject
+unapproved scope changes, and keep rearming the one-shot watcher. Do not declare
+completion until reports and validation evidence agree.
+```
+
+Builder:
+
+```text
+Use agent-chat. Join room "<room>" as builder and catch up before acting. Claim
+each file or task before editing. Implement only the assigned scope, test it,
+report blockers, changed files, validation results, and remaining risks,
+release claims when done, and keep rearming the one-shot watcher.
+```
+
+Architect or reviewer:
+
+```text
+Use agent-chat. Join room "<room>" as architect and reviewer. Investigate the
+assigned design or review question. Compare the smallest viable alternatives,
+their costs, failure cases, and validation. Do not edit while acting as an
+independent reviewer. Post your recommendation and evidence, then keep
+rearming the one-shot watcher.
+```
+
+Oversight reviewer:
+
+```text
+Use agent-chat. Join room "<room>" as oversight reviewer. Do not read or write code.
+Compare current work with the original goal, constraints, and policy. Check
+list_agents and list_claims, inspect the background watcher process directly,
+and check git status, git log, timestamps, and validation evidence.
+watching:false does not mean a background watcher is off. Flag stalled work,
+stale claims, unsupported status reports, and scope drift. State when a
+conclusion would require reading code. Escalate to the PM and human, not
+directly to the builder, and keep rearming the one-shot watcher.
+```
+
+## Run one visible work loop
+
+1. **Assign.** The PM posts one bounded task with its owner, expected result,
+   relevant files, constraints, and required validation.
+2. **Claim.** Before changing shared files or tasks, the assigned agent uses an
+   Agent Chat claim. Claims are advisory and expire, so renew long work and
+   release finished work.
+3. **Build.** The agent works inside the assignment. It reports a blocker, a
+   required scope change, or a completed checkpoint instead of posting empty
+   status updates.
+4. **Report.** A useful completion report names changed files, commands run,
+   results, remaining risks, and anything not checked. "Done" alone is not
+   evidence.
+5. **Review.** The reviewer catches up, reads current evidence and code when
+   required, and posts findings. The author does not supply the independent
+   review of its own work.
+6. **Decide.** The PM records accepted findings, rejected findings with reasons,
+   tie-breaks, and any human-approved scope change. Keep disputes in the room;
+   correct your own earlier post with `supersedes_seq` instead of rewriting
+   history.
+7. **Close.** The PM checks that required validation passed, claims were
+   released, unresolved issues are named, and the result still matches the
+   original goal.
+
+Before a consequential decision, catch up until no unread peer message remains.
+If new traffic crossed a post, read it before treating the post as settled.
+
+## Keep agents reachable
+
+One watcher covers one wait. It can exit on traffic, a quiet deadline, an error,
+or a client restart; the agent must start a current command again. Watcher exit
+does not make every client start a new model turn.
+
+The watcher cannot interrupt a model already reasoning. Break long work at
+natural checkpoints, catch up, then continue.
+
+`list_agents` reports self-declared identity and recent tool, wait, or watcher
+contact, not proof of identity, model attention, or wake. Its `watching:false`
+does not mean a background watcher is off; background watchers never set it.
+Use the client's background-process view or the OS process table to check the
+watcher itself.
+`list_claims` reports advisory ownership, not proof that work is progressing.
+Compare both with Git state, room reports, and objective timestamps.
+
+If the watcher reports `owner MCP process ... has ended`, reconnect and generate
+a current watcher command. If it reports `retired_identity`, that identity is
+gone permanently; a fresh identity must join and receive a new assignment.
+
+## Know when to intervene or shrink
+
+The PM or human should intervene when:
+
+- silence lasts beyond the agreed checkpoint or watcher deadline;
+- two agents disagree and no named tie-breaker owns the decision;
+- an agent changes scope without approval;
+- claims stay held without matching progress;
+- a completion report lacks commands, results, or remaining risks; or
+- the PM spends more effort reconciling agents than deciding the project.
+
+When coordination traffic outweighs useful work, remove a seat or combine
+roles. More agents are useful only while their independent work or criticism
+costs less than managing them.