multi-agent-collaboration-mcp 0.13.0 → 0.16.0

package/dist/poller.js

@@ -9,8 +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>] [--epoch <n>]
-            [--owner-pid <pid>]
+  poller.js --agent <id> [--room <id|name>] [--owner-pid <pid>]
             [--mentions-only] [--interval <seconds>] [--timeout <seconds>]
             [--ok-on-timeout]
 
@@ -18,13 +17,24 @@ The interval must be 5..3600 seconds (default 5). The timeout must be
 1..86400 seconds (default 1200). Exit 0 = work exists; with --ok-on-timeout,
 exit 0 also reports a quiet deadline as has_updates:false. Without it,
 timeout exits 124. Exit 2 = invalid arguments, duplicate watcher, DB error, or
-a stale binding (the persona was resumed by a newer runtime).
+a terminal watcher state. Inspect stderr before re-arming:
+  retired_identity      persona is terminally retired; it can never watch again
+  left_room             persona left the scoped room
+  left_all_rooms        persona left every joined room
+  no_room_memberships   persona has no remaining room memberships
 
---epoch binds this watcher to one runtime tenure of the persona. Every probe
-reads the persona's current epoch; once it moves, this watcher is speaking for
-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.
+retired_identity is the one state no new command can fix. The others describe a
+persona that still exists and can rejoin; a retired persona cannot, so it takes
+precedence over every membership state. A retired persona keeps its history and
+its non-advancing reads still work; what it can never do again is post, advance
+a read marker, claim, join, or be watched.
+
+There is no tenure argument. An agent_id is allocated once and never deleted,
+reinserted, revived, or rebound, so it names one identity for the life of the
+database; every probe re-reads that identity's live state, which is the whole
+fence. --owner-pid alone marks a GENERATED watcher owned by an MCP process and
+enables its guarded liveness heartbeat; without it the watcher is strictly
+read-only.
 `;
 function argumentError(message) {
     throw new Error(message);
@@ -41,7 +51,6 @@ function parseInteger(value, flag, min, max) {
 function parseArgs(argv) {
     let agent;
     let room;
-    let epoch;
     let ownerPid;
     let db;
     let mentionsOnly = false;
@@ -67,9 +76,6 @@ function parseArgs(argv) {
             agent = take();
         else if (flag === "--room")
             room = 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);
         }
@@ -111,7 +117,6 @@ function parseArgs(argv) {
     return {
         agent,
         room,
-        epoch,
         ownerPid,
         db,
         mentionsOnly,
@@ -165,11 +170,11 @@ function acquireLock(path, token) {
         }
         catch { }
         if (processIsAlive(owner)) {
-            argumentError(`an equivalent watcher is already running (pid ${owner}; lock: ${path})`);
+            argumentError(`watcher lock references live pid ${owner}; refusing a duplicate (lock: ${path})`);
         }
         // Fail closed. Automatic stale-lock stealing needs a second interprocess
         // lock to avoid two reapers deleting each other's replacement.
-        argumentError(`stale watcher lock requires removal: ${path}`);
+        argumentError(`stale watcher lock file: ${path}; remove only this exact file, then retry`);
     }
 }
 const sleep = (milliseconds) => new Promise((done) => setTimeout(done, milliseconds));
@@ -245,12 +250,12 @@ try {
     database = new Database(path);
     database.pragma("busy_timeout = 2000");
     // A GENERATED runtime watcher -- one this server's wait_for_messages handed
-    // out, identified by carrying both --owner-pid and --epoch -- refreshes its
+    // out, identified by carrying --owner-pid -- 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
+    // watcher without it (a hand-run diagnostic watch) stays strictly
     // read-only.
-    const heartbeatEnabled = args.ownerPid !== undefined && args.epoch !== undefined;
+    const heartbeatEnabled = args.ownerPid !== undefined;
     if (!heartbeatEnabled)
         database.pragma("query_only = ON");
     let resolvedRoom;
@@ -280,17 +285,16 @@ try {
     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.
+    // Owned and diagnostic watches have different functions: the owned watcher
+    // maintains liveness while the diagnostic watcher is read-only. Keep their
+    // locks separate so a stray diagnostic cannot block the generated wake
+    // channel and heartbeat. The numeric owner PID is not part of the identity;
+    // only the watcher class matters.
     const scopeKey = JSON.stringify([
         path,
         args.agent,
         resolvedRoom?.id ?? null,
-        args.epoch ?? null,
+        args.ownerPid === undefined ? "diagnostic" : "owned",
         args.mentionsOnly,
     ]);
     const lockName = createHash("sha256").update(scopeKey).digest("hex") + ".lock";
@@ -301,28 +305,84 @@ try {
     acquireLock(lockPath, lockToken);
     const params = { agent: args.agent };
     /**
-     * A watcher bound to an epoch stops the moment the persona moves on.
+     * A terminally retired identity can never watch again.
      *
-     * 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.
+     * Checked unconditionally on every watcher, generated or hand-run. This is
+     * the complete identity fence: an agent_id has one tenure, so "is this
+     * identity finished" is the only question, and a watcher for a finished one
+     * must exit rather than report traffic to a seat that cannot act on it or
+     * advance its marker over it.
+     *
+     * It also takes precedence over every membership state. "left the room" and
+     * "no memberships" describe a persona that can rejoin; a retired one cannot,
+     * and telling a caller to rejoin would be advice that cannot be followed.
      */
-    const checkEpoch = (current) => {
-        if (args.epoch === undefined)
-            return;
-        if (current === null) {
-            argumentError(`persona "${args.agent}" no longer exists; this watcher's binding is dead`);
+    const checkRetired = (retiredAt) => {
+        if (retiredAt !== null) {
+            argumentError(`retired_identity: persona "${args.agent}" is terminally retired. No ` +
+                `watcher can represent it, and it can never post, advance a read ` +
+                `marker, claim, or join again; its history stands and non-advancing ` +
+                `reads of it still work. No new poller command will work for it. ` +
+                `Identify a live persona and arm a watcher from that.`);
         }
-        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.`);
+    };
+    /**
+     * A VANISHED persona stops every watcher, generated or hand-run. Looping
+     * quietly against a deleted row is the one outcome no caller can interpret,
+     * so it is a terminal exit rather than a quiet continue.
+     */
+    const checkExists = (exists) => {
+        if (!exists) {
+            argumentError(`persona "${args.agent}" no longer exists; this watcher has nothing to watch`);
         }
     };
+    // ARM-TIME identity gate, before ANY membership state is consulted, for both
+    // the scoped and all-room paths.
+    //
+    // Order is the point: identity outranks membership. A retired persona must
+    // report retired_identity rather than left_room / left_all_rooms /
+    // no_room_memberships, all of which imply a recoverable situation.
+    //
+    // Read identity and membership from one snapshot.
+    //
+    // Read as separate autocommit statements these disagree, and the disagreement
+    // is exactly the ordering this gate exists to enforce: retirement updates
+    // agents.retired_at and soft-leaves memberships in ONE immediate transaction,
+    // so a retirement committing between the two reads leaves identity looking
+    // live and membership looking left -- and startup then reports left_room or
+    // left_all_rooms for a persona that is actually retired. A deferred read
+    // transaction makes both reads see the same snapshot, so they cannot describe
+    // two different moments. It covers startup only and is not held into the
+    // probe loop.
+    // Bound to a const first: `database` is a mutable module-level binding, so
+    // TypeScript cannot keep its non-null narrowing inside a closure.
+    const conn = database;
+    const startup = conn
+        .transaction(() => {
+        const persona = conn
+            .prepare("SELECT retired_at FROM agents WHERE id = ?")
+            .get(args.agent);
+        const membership = resolvedRoom
+            ? conn
+                .prepare("SELECT left_at FROM memberships WHERE room_id = ? AND agent_id = ?")
+                .get(resolvedRoom.id, args.agent)
+            : undefined;
+        const counts = resolvedRoom
+            ? undefined
+            : conn
+                .prepare(`SELECT COUNT(*) AS total,
+                      COALESCE(SUM(CASE WHEN left_at IS NULL THEN 1 ELSE 0 END), 0)
+                        AS present
+               FROM memberships WHERE agent_id = ?`)
+                .get(args.agent);
+        return { persona, membership, counts };
+    })
+        .deferred();
+    const armPersona = startup.persona;
+    if (!armPersona) {
+        argumentError(`no persona "${args.agent}"; identify a persona and arm a watcher from it`);
+    }
+    checkRetired(armPersona.retired_at);
     const directed = args.mentionsOnly
         ? ` AND (g.mentions IS NOT NULL OR g.reply_to_agent IS NOT NULL)
         AND (EXISTS (SELECT 1 FROM json_each(g.mentions) WHERE value = @agent)
@@ -330,9 +390,8 @@ try {
         : "";
     let probe;
     if (resolvedRoom) {
-        const membership = database
-            .prepare("SELECT left_at FROM memberships WHERE room_id = ? AND agent_id = ?")
-            .get(resolvedRoom.id, args.agent);
+        // From the startup snapshot, not a fresh read: see the transaction above.
+        const membership = startup.membership;
         if (!membership) {
             argumentError(`agent "${args.agent}" has not joined room ${resolvedRoom.id}`);
         }
@@ -343,12 +402,20 @@ try {
                 `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.
+        // has_updates, retired_at 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.
+        //
+        // The agents row arrives through a LEFT JOIN rather than two scalar
+        // subqueries. Measured, not assumed: EXPLAIN QUERY PLAN on the subquery
+        // form showed TWO `SEARCH a USING INDEX sqlite_autoindex_agents_1 (id=?)`
+        // entries, one per subquery; the LEFT JOIN form shows one. LEFT, not inner,
+        // so a vanished persona cannot turn this into "no row" -- that phrase has
+        // to keep meaning the room or membership is gone, and a null agents_id
+        // is how a vanished persona reports itself.
         const statement = database.prepare(`SELECT r.name AS room_name,
-              (SELECT a.runtime_epoch FROM agents a WHERE a.id = @agent)
-                AS current_epoch,
+              a.id AS agents_id,
+              a.retired_at AS retired_at,
               mb.left_at AS left_at,
               EXISTS (
                 SELECT 1 FROM messages g
@@ -359,22 +426,25 @@ try {
               ) AS has_updates
        FROM rooms r
        JOIN memberships mb ON mb.room_id = r.id AND mb.agent_id = @agent
+       LEFT JOIN agents a ON a.id = @agent
        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);
+            // Identity FIRST: existence, then retirement, then membership.
+            checkExists(row.agents_id !== null);
+            checkRetired(row.retired_at);
             // 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
+            // returned DATA for the same reason retirement 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
+            // This is a DIFFERENT exit from retired_identity. Both say do not
+            // re-arm this command, but one means the identity is finished 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) {
@@ -389,18 +459,28 @@ try {
         };
     }
     else {
-        const present = database
-            .prepare("SELECT 1 FROM memberships WHERE agent_id = ? AND left_at IS NULL LIMIT 1")
-            .get(args.agent);
-        if (!present)
-            argumentError(`agent "${args.agent}" is not present in any room`);
-        // ANCHORED on the persona row, not on memberships. The unread test alone
-        // returns ZERO rows on a quiet interval -- the normal case -- so there is no
-        // row to hang an epoch column on. Selecting FROM agents makes the result
-        // exactly one row whenever the persona exists, carrying the epoch every
-        // time and the hit only when there is one. A vanished persona yields no row,
-        // which checkEpoch reads as a dead binding rather than as silence.
-        const statement = database.prepare(`SELECT a.runtime_epoch AS current_epoch,
+        // From the startup snapshot, not a fresh read: see the transaction above.
+        const membershipCounts = startup.counts;
+        if (membershipCounts.total === 0) {
+            argumentError(`no_room_memberships: agent "${args.agent}" has no room memberships; ` +
+                "join a room and generate a fresh poller command");
+        }
+        if (membershipCounts.present === 0) {
+            argumentError(`left_all_rooms: agent "${args.agent}" has left every joined room; ` +
+                "rejoin one with join_room and use the new poller command");
+        }
+        // Anchor on the persona so every quiet probe still returns retirement and
+        // membership state. A vanished persona yields no row.
+        const statement = database.prepare(`SELECT a.retired_at AS retired_at,
+              EXISTS (
+                SELECT 1 FROM memberships all_mb
+                WHERE all_mb.agent_id = @agent
+              ) AS has_membership,
+              EXISTS (
+                SELECT 1 FROM memberships present_mb
+                WHERE present_mb.agent_id = @agent
+                  AND present_mb.left_at IS NULL
+              ) AS has_present,
               (SELECT mb.room_id FROM memberships mb
                 WHERE mb.agent_id = @agent AND mb.left_at IS NULL
                   AND EXISTS (
@@ -415,8 +495,22 @@ try {
         const roomName = database.prepare("SELECT name FROM rooms WHERE id = ?");
         probe = () => {
             const row = statement.get(params);
-            checkEpoch(row ? row.current_epoch : null);
-            if (!row || row.room_id === null)
+            // No row means the persona itself is gone; that is terminal, not quiet.
+            checkExists(!!row);
+            // Retirement outranks BOTH membership states below, so a retired persona
+            // never reports left_all_rooms or no_room_memberships -- both of which
+            // would tell the caller to rejoin, which it cannot do.
+            checkRetired(row.retired_at);
+            if (!row.has_membership) {
+                argumentError(`no_room_memberships: agent "${args.agent}" has no remaining room ` +
+                    "memberships; join a room and generate a fresh poller command");
+            }
+            if (!row.has_present) {
+                argumentError(`left_all_rooms: agent "${args.agent}" left every joined room while ` +
+                    "this watcher was armed; rejoin one with join_room and use the new " +
+                    "poller command");
+            }
+            if (row.room_id === null)
                 return undefined;
             // Name lookup only on a HIT, so the quiet path stays one statement.
             const named = roomName.get(row.room_id);
@@ -428,12 +522,13 @@ try {
     /**
      * 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.
+     * ONE prepared, fenced UPDATE. The EXISTS clause is the fence, and it tests
+     * retirement: a watcher whose identity is finished matches no row. Without
+     * it a retired seat could keep refreshing last_seen for up to one probe
+     * interval, advertising a live listener that can never act. 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.
@@ -450,7 +545,7 @@ try {
         ? 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)`)
+                         WHERE a.id = @agent AND a.retired_at IS NULL)`)
         : null;
     let lastHeartbeatMs = 0;
     const heartbeat = () => {
@@ -466,13 +561,11 @@ try {
         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)) {
@@ -491,6 +584,10 @@ try {
                     room_id: hit.room_id,
                     room_name: hit.room_name,
                     mentions_only: args.mentionsOnly,
+                    next: `catch_up room ${hit.room_id} until \`remaining\` is 0 or stops ` +
+                        "falling; then re-run this command before working. The watcher " +
+                        "checks before sleeping, so unread traffic makes it exit " +
+                        "immediately.",
                 }) + "\n", (error) => (error ? rejectWrite(error) : resolveWrite()));
             });
             exitCode = 0;
@@ -499,7 +596,11 @@ try {
         if (Date.now() >= deadline) {
             if (args.timeoutOk) {
                 await new Promise((resolveWrite, rejectWrite) => {
-                    process.stdout.write('{"has_updates":false,"timed_out":true}\n', (error) => (error ? rejectWrite(error) : resolveWrite()));
+                    process.stdout.write(JSON.stringify({
+                        has_updates: false,
+                        timed_out: true,
+                        next: "re-run this same command immediately to keep watching.",
+                    }) + "\n", (error) => (error ? rejectWrite(error) : resolveWrite()));
                 });
                 exitCode = 0;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multi-agent-collaboration-mcp",
-  "version": "0.13.0",
+  "version": "0.16.0",
   "description": "MCP server: a shared chat room where AI agents coordinate via a SQLite-backed message log",
   "license": "Apache-2.0",
   "repository": {
@@ -13,7 +13,8 @@
   "bin": {
     "multi-agent-collaboration-mcp": "dist/index.js",
     "agent-chat-check": "dist/check.js",
-    "agent-chat-poller": "dist/poller.js"
+    "agent-chat-poller": "dist/poller.js",
+    "agent-chat-web": "web/server.mjs"
   },
   "main": "dist/index.js",
   "files": [

package/scripts/connection-probe.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+
+import { createHash, randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const connectionId = randomUUID();
+const probeStartedAt = new Date().toISOString();
+let nickname = null;
+let loginCalls = 0;
+
+const SENSITIVE_KEY =
+  /authorization|cookie|credential|password|secret|session|token|api[-_]?key/i;
+const MAX_STRING_CHARS = 2_000;
+const MAX_ARRAY_ITEMS = 100;
+const MAX_OBJECT_KEYS = 100;
+const MAX_DEPTH = 6;
+
+function fingerprint(value) {
+  return createHash("sha256").update(String(value)).digest("hex");
+}
+
+function sanitize(value, depth = 0) {
+  if (value === null || value === undefined) return value ?? null;
+  if (depth >= MAX_DEPTH) return "[depth limit]";
+  if (typeof value === "string") {
+    return value.length <= MAX_STRING_CHARS
+      ? value
+      : `${value.slice(0, MAX_STRING_CHARS)}...[truncated ${value.length - MAX_STRING_CHARS} chars]`;
+  }
+  if (
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+  if (typeof value === "bigint") return value.toString();
+  if (value instanceof URL) {
+    const safe = new URL(value);
+    if (safe.username) safe.username = "[redacted]";
+    if (safe.password) safe.password = "[redacted]";
+    for (const key of safe.searchParams.keys()) {
+      if (SENSITIVE_KEY.test(key)) safe.searchParams.set(key, "[redacted]");
+    }
+    return safe.toString();
+  }
+  if (Array.isArray(value)) {
+    const entries = value
+      .slice(0, MAX_ARRAY_ITEMS)
+      .map((entry) => sanitize(entry, depth + 1));
+    if (value.length > MAX_ARRAY_ITEMS) {
+      entries.push(`[truncated ${value.length - MAX_ARRAY_ITEMS} items]`);
+    }
+    return entries;
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value);
+    const safe = {};
+    for (const [key, entry] of entries.slice(0, MAX_OBJECT_KEYS)) {
+      safe[key] = SENSITIVE_KEY.test(key)
+        ? {
+            redacted: true,
+            sha256: fingerprint(
+              typeof entry === "string" ? entry : JSON.stringify(entry),
+            ),
+          }
+        : sanitize(entry, depth + 1);
+    }
+    if (entries.length > MAX_OBJECT_KEYS) {
+      safe._truncated_keys = entries.length - MAX_OBJECT_KEYS;
+    }
+    return safe;
+  }
+  return String(value);
+}
+
+function safeAuthInfo(authInfo) {
+  if (!authInfo) return null;
+  return {
+    client_id: authInfo.clientId,
+    scopes: sanitize(authInfo.scopes),
+    expires_at: authInfo.expiresAt ?? null,
+    resource: sanitize(authInfo.resource),
+    token: {
+      redacted: true,
+      sha256: fingerprint(authInfo.token),
+    },
+    extra: sanitize(authInfo.extra),
+  };
+}
+
+const server = new McpServer(
+  {
+    name: "agent-chat-connection-probe",
+    version: "0.1.0",
+  },
+  {
+    instructions:
+      "Call connection_login. Repeated calls through one MCP connection return " +
+      "the same connection_id and nickname. Separately launched MCP processes " +
+      "return different values.",
+  },
+);
+
+server.registerTool(
+  "connection_login",
+  {
+    title: "Inspect MCP connection identity",
+    description:
+      "Assign and report this MCP server process's connection identity. The " +
+      "first call assigns it; later calls reuse it.",
+    inputSchema: z.object({}).strict(),
+  },
+  async (_args, extra) => {
+    const assignedNow = nickname === null;
+    if (assignedNow) nickname = `connection-${connectionId}`;
+    loginCalls += 1;
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              connection_id: connectionId,
+              nickname,
+              assigned_now: assignedNow,
+              login_calls: loginCalls,
+              observed_at: new Date().toISOString(),
+              process: {
+                pid: process.pid,
+                parent_pid: process.ppid,
+                probe_started_at: probeStartedAt,
+                working_directory: process.cwd(),
+                executable: process.execPath,
+                argv: sanitize(process.argv),
+                title: process.title,
+                node_version: process.version,
+                platform: process.platform,
+                architecture: process.arch,
+                hostname: hostname(),
+                uid: process.getuid?.() ?? null,
+                gid: process.getgid?.() ?? null,
+                stdin_is_tty: process.stdin.isTTY === true,
+                stdout_is_tty: process.stdout.isTTY === true,
+              },
+              mcp: {
+                transport: "stdio",
+                transport_session_id:
+                  extra.sessionId === undefined
+                    ? null
+                    : {
+                        redacted: true,
+                        sha256: fingerprint(extra.sessionId),
+                      },
+                client_reported_info: sanitize(
+                  server.server.getClientVersion(),
+                ),
+                client_reported_capabilities: sanitize(
+                  server.server.getClientCapabilities(),
+                ),
+                request: {
+                  jsonrpc_request_id: extra.requestId,
+                  task_id: extra.taskId ?? null,
+                  task_requested_ttl: extra.taskRequestedTtl ?? null,
+                  metadata: sanitize(extra._meta),
+                  http:
+                    extra.requestInfo === undefined
+                      ? null
+                      : {
+                          url: sanitize(extra.requestInfo.url),
+                          headers: sanitize(extra.requestInfo.headers),
+                        },
+                  auth: safeAuthInfo(extra.authInfo),
+                },
+                field_sources: {
+                  connection_id:
+                    "Generated by this probe process; not supplied by MCP.",
+                  client_reported_info:
+                    "initialize.params.clientInfo supplied by the MCP client.",
+                  client_reported_capabilities:
+                    "initialize.params.capabilities supplied by the MCP client.",
+                  transport_session_id:
+                    "RequestHandlerExtra.sessionId when the transport supplies one.",
+                },
+              },
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  },
+);
+
+let shutdownPromise;
+function shutdown(exitCode) {
+  if (shutdownPromise) return shutdownPromise;
+  process.exitCode = exitCode;
+  shutdownPromise = server.close().catch(() => undefined);
+  return shutdownPromise;
+}
+
+process.stdin.once("end", () => void shutdown(0));
+process.once("SIGINT", () => void shutdown(130));
+process.once("SIGTERM", () => void shutdown(143));
+
+try {
+  await server.connect(new StdioServerTransport());
+  process.stderr.write(
+    `connection probe ready (connection_id: ${connectionId}, pid: ${process.pid})\n`,
+  );
+} catch (error) {
+  process.stderr.write(
+    `connection probe failed: ${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exitCode = 1;
+}