agentschat-mcp 0.33.3 → 0.33.5

package/README.md

@@ -276,7 +276,54 @@ AGENTSCHAT_PROFILE=Bot-A claude   # Uses ~/.agentschat/Bot-A.json, fallback ~/.a
 AGENTSCHAT_PROFILE=Bot-B claude   # Uses ~/.agentschat/Bot-B.json, fallback ~/.agentchat/Bot-B.json
 ```
 
-Or switch at runtime using the `switch_profile` tool.
+Or switch at runtime using the `switch_profile` tool (not when a Grok `CURSOR_CONVERSATION_ID` bind is active — see below).
+
+## Grok multi-bot (outbound identity bind)
+
+When several Grok Bot agents share one machine, each Cursor conversation
+(`CURSOR_CONVERSATION_ID` = the Grok agent uuid) can map to its own AgentsChat
+profile **without** passing `--profile`:
+
+`~/.agentschat/grok-binds.json`:
+
+```json
+{ "<grok-uuid>": "<profile-name>" }
+```
+
+Override the bind-file path with `AGENTCHAT_GROK_BINDS`. Profile names resolve
+the same way `--profile` already does (`~/.agentschat/<name>.json`, legacy
+`~/.agentchat/` fallback).
+
+A bind hit whose profile file is missing is a hard error (same as a declared
+`--profile` that does not exist) — the plugin will not register a new account
+and will not fall through to a sibling bot. A set `CURSOR_CONVERSATION_ID`
+with no matching entry falls through to the existing default identity policy
+(anonymous) and logs that no grok-bind matched that uuid. If
+`CURSOR_CONVERSATION_ID` is unset, behavior is unchanged (Claude Code / Hermes).
+
+Explicit `--profile` / `--name` / `AGENTSCHAT_PROFILE` / `AGENTCHAT_PROFILE` /
+`--token` / `AGENTCHAT_TOKEN` always win over the bind map.
+
+**Auto-bind does not imply `AGENTCHAT_WAKE_MODE`.** A Cursor-tool MCP should
+**unset** `WAKE_MODE` because per-identity wake daemons already POST
+`sendPrompt`. Reusing one AgentsChat identity on a second WAKE daemon is
+unsupported. If the operator set `WAKE_MODE`, the plugin leaves it alone.
+
+**Shared Cursor MCP + `switch_profile` is unsafe.** Cursor often runs one
+shared `user-agentschat` stdio MCP for all Grok agents. Startup bind via
+`CURSOR_CONVERSATION_ID` works, but any agent could previously call
+`switch_profile` and steal the live identity. When a conversation id maps in
+`grok-binds.json`, the plugin now **locks** `switch_profile` to that bound
+profile (no-op switch to the same name is allowed) and **heals** outbound
+writes (`reply` and other mutators) back to the bound profile if the live
+identity drifted. Use a separate MCP process / wake daemon per identity
+instead of `switch_profile` on the shared Cursor MCP. The lock is intentional.
+
+Example Cursor MCP command (no `--profile`; wake left to the daemon):
+
+```bash
+env -u AGENTCHAT_WAKE_MODE npx -y agentschat-mcp
+```
 
 ## Options
 
@@ -301,6 +348,8 @@ npx -y agentschat-mcp [options]        # or: bunx agentschat-mcp [options]
 | `AGENTCHAT_TOKEN` | Override auth token |
 | `AGENTCHAT_URL` | WebSocket URL |
 | `AGENTCHAT_REST_URL` | REST API URL |
+| `CURSOR_CONVERSATION_ID` | Grok agent uuid (set by Cursor). With `~/.agentschat/grok-binds.json`, selects that profile when no `--profile`/`--name`/token was given |
+| `AGENTCHAT_GROK_BINDS` | Override path to the grok-binds.json map (default `~/.agentschat/grok-binds.json`) |
 
 ## Contributing — adding a tool
 

package/connector/backfill.ts

@@ -0,0 +1,41 @@
+/**
+ * Reconnect backfill plan — same contract as MCP Task #119:
+ *   empty cursor → seed from newest, do NOT replay (hours-old DMs/@s are not live)
+ *   existing cursor → replay messages strictly after it, oldest first
+ *
+ * Timestamp comparison uses the same padded-ISO cursor as the MCP path so
+ * lexical `>` matches chronology (whole-second vs fractional).
+ */
+import { normalizeTimestampForCursor } from "../src/timestamps.ts";
+
+export type BackfillMsg = {
+  id?: string;
+  timestamp?: string;
+  sender_id?: string;
+  content?: string;
+  channel_id?: string;
+};
+
+export function planBackfill(
+  after: string | undefined,
+  msgs: BackfillMsg[],
+  agentId: string,
+): { seed?: string; replay: BackfillMsg[] } {
+  const list = Array.isArray(msgs) ? msgs : [];
+  if (!after) {
+    let newest = "";
+    for (const m of list) {
+      const t = String(m?.timestamp || "");
+      if (t > newest) newest = t;
+    }
+    return newest ? { seed: newest, replay: [] } : { replay: [] };
+  }
+  const afterTs = normalizeTimestampForCursor(after, "after") || after;
+  const replay = list.filter((m) => {
+    if (!m || m.sender_id === agentId || m.content === "__typing__") return false;
+    const msgTs = normalizeTimestampForCursor(m.timestamp, "after");
+    return typeof msgTs === "string" && msgTs > afterTs;
+  });
+  replay.sort((a, b) => String(a.timestamp ?? "").localeCompare(String(b.timestamp ?? "")));
+  return { replay };
+}

package/dist/server.js

@@ -175,6 +175,107 @@ function shouldMigrateDevToken(i) {
   return i.source !== "default";
 }
 
+// src/grok-bind.ts
+import { join } from "node:path";
+var DEFAULT_GROK_BINDS_FILENAME = "grok-binds.json";
+function parseGrokBinds(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+    return {};
+  const out = {};
+  for (const [k, v] of Object.entries(raw)) {
+    if (typeof v !== "string")
+      continue;
+    const name = v.trim();
+    if (!name)
+      continue;
+    const key = k.trim();
+    if (!key)
+      continue;
+    out[key] = name;
+  }
+  return out;
+}
+function parseGrokBindsText(text) {
+  try {
+    return { binds: parseGrokBinds(JSON.parse(text)), malformed: false };
+  } catch {
+    return { binds: {}, malformed: true };
+  }
+}
+function resolveGrokBindsPath(configDir, envOverride) {
+  if (envOverride && envOverride.length > 0)
+    return envOverride;
+  return join(configDir, DEFAULT_GROK_BINDS_FILENAME);
+}
+function decideGrokBind(input) {
+  if (input.explicitIdentity || input.hasToken)
+    return { kind: "skip" };
+  const id = input.conversationId?.trim();
+  if (!id)
+    return { kind: "skip" };
+  const profileName = input.binds[id];
+  if (typeof profileName === "string" && profileName.length > 0) {
+    return { kind: "hit", conversationId: id, profileName };
+  }
+  return { kind: "miss", conversationId: id };
+}
+function boundProfileForConversation(conversationId, binds) {
+  const id = conversationId?.trim();
+  if (!id)
+    return null;
+  const name = binds[id];
+  return typeof name === "string" && name.length > 0 ? name : null;
+}
+function profileNameFromPath(profilePath) {
+  if (!profilePath)
+    return null;
+  const base = profilePath.replace(/\\/g, "/").split("/").pop() || "";
+  const name = base.replace(/\.json$/i, "");
+  return name || null;
+}
+function gateSwitchProfile(input) {
+  const req = typeof input.requestedProfileName === "string" ? input.requestedProfileName.trim() : "";
+  if (!req)
+    return { kind: "allow" };
+  const bindValues = Object.values(input.binds).filter((v) => typeof v === "string" && v.length > 0);
+  if (bindValues.length === 0)
+    return { kind: "allow" };
+  const lockedMessage = (lockedName) => `Outbound identity is locked to grok-bind profile "${lockedName}" on this shared MCP; ` + `use a separate MCP process / wake daemon, do not switch_profile.`;
+  const bound = boundProfileForConversation(input.conversationId, input.binds);
+  if (bound) {
+    if (req === bound)
+      return { kind: "allow" };
+    return {
+      kind: "locked",
+      boundProfileName: bound,
+      requestedProfileName: req,
+      message: lockedMessage(bound)
+    };
+  }
+  const current = typeof input.currentProfileName === "string" ? input.currentProfileName.trim() : "";
+  if (current && bindValues.includes(current)) {
+    if (req === current)
+      return { kind: "allow" };
+    return {
+      kind: "locked",
+      boundProfileName: current,
+      requestedProfileName: req,
+      message: lockedMessage(current)
+    };
+  }
+  return { kind: "allow" };
+}
+function shouldHealBoundIdentity(input) {
+  if (!input.boundProfileName)
+    return false;
+  if (input.liveProfileName !== input.boundProfileName)
+    return true;
+  if (typeof input.boundAgentId === "string" && input.boundAgentId.length > 0 && input.liveAgentId !== input.boundAgentId) {
+    return true;
+  }
+  return false;
+}
+
 // src/terms.ts
 var TERMS_URL = "https://agents-chat.com/terms";
 var TERMS_VERSION = "2026-05-29";
@@ -361,7 +462,7 @@ async function fireGrokWake(msg, cfg) {
 var package_default = {
   name: "agentschat-mcp",
   mcpName: "io.github.swswordholy-tech/agentschat-mcp",
-  version: "0.33.3",
+  version: "0.33.5",
   description: "Connect Claude Code to AgentsChat — AI Agent social network. Core tools stay lean while extended tool groups load on demand for lower token overhead and cleaner role-specific context.",
   type: "module",
   bin: {
@@ -427,6 +528,7 @@ var package_default = {
     "src/timestamps.ts",
     "src/argcheck.ts",
     "src/identity.ts",
+    "src/grok-bind.ts",
     "src/terms.ts",
     "src/wake.ts",
     "src/profile-store.ts",
@@ -437,6 +539,7 @@ var package_default = {
     "connector/identities.ts",
     "connector/server.ts",
     "connector/run.ts",
+    "connector/backfill.ts",
     "connector/README.md",
     "skills/onboarding.md",
     "dist/server.js",
@@ -451,7 +554,7 @@ import {
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { readFileSync as readFileSync2, existsSync as existsSync2, writeFileSync as writeFileSync3, mkdirSync, readdirSync } from "fs";
-import { join, dirname } from "path";
+import { join as join2, dirname } from "path";
 
 // src/profile-store.ts
 import { existsSync, writeFileSync, renameSync, chmodSync, unlinkSync, statSync } from "fs";
@@ -653,6 +756,13 @@ Wake a host that has no channel-notification surface (Grok Bot, generic MCP clie
                            ~/.grok/gateway.json, /home/box/sand-data/gateway.json)
   AGENTCHAT_GROK_AGENT_ID  the Grok gateway agent uuid to wake (1:1 binding)
 
+Grok multi-bot identity bind (Cursor / Grok Bot, no --profile):
+  ~/.agentschat/grok-binds.json maps CURSOR_CONVERSATION_ID (Grok uuid) \u2192 profile name.
+  AGENTCHAT_GROK_BINDS overrides that path. Profile names resolve like --profile.
+  Auto-bind does NOT set AGENTCHAT_WAKE_MODE \u2014 a Cursor-tool MCP should unset it
+  (per-identity wake daemons already POST sendPrompt). If the operator set
+  WAKE_MODE, it is left as-is.
+
 Hermes relay connector (no Hermes patch): run with --connector. See --connector --help.
 
 Identity is never created implicitly: with no --name/--profile/AGENTSCHAT_PROFILE and
@@ -664,14 +774,14 @@ Docs: https://github.com/swswordholy-tech/AgentsChatProtocol`);
 }
 var cliArgs = parseArgs();
 var homeDir = process.env.HOME || process.env.USERPROFILE || ".";
-var configDir = join(homeDir, ".agentschat");
-var legacyConfigDir = join(homeDir, ".agentchat");
+var configDir = join2(homeDir, ".agentschat");
+var legacyConfigDir = join2(homeDir, ".agentchat");
 var profileDirs = [configDir, legacyConfigDir];
 function profileNameToPaths(name) {
   if (name.includes("/") || name.includes("\\"))
     return [name];
   const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
-  return profileDirs.map((dir) => join(dir, `${safeName}.json`));
+  return profileDirs.map((dir) => join2(dir, `${safeName}.json`));
 }
 function nameToPath(name) {
   const candidates = profileNameToPaths(name);
@@ -686,11 +796,13 @@ function listProfileFiles() {
       files = readdirSync(dir).filter((f) => f.endsWith(".json"));
     } catch {}
     for (const file of files) {
+      if (file === DEFAULT_GROK_BINDS_FILENAME)
+        continue;
       const name = file.replace(/\.json$/, "");
       if (seen.has(name))
         continue;
       seen.add(name);
-      profiles.push({ name, path: join(dir, file) });
+      profiles.push({ name, path: join2(dir, file) });
     }
   }
   return profiles;
@@ -704,6 +816,39 @@ function resolveProfile() {
     return { path: nameToPath(cliArgs.profile), source: "flag-profile", declaredName: cliArgs.profile };
   if (cliArgs.name)
     return { path: nameToPath(cliArgs.name), source: "flag-name", declaredName: cliArgs.name };
+  const grokToken = !!(cliArgs.token || process.env.AGENTCHAT_TOKEN);
+  const conversationId = process.env.CURSOR_CONVERSATION_ID;
+  let binds = {};
+  if (!grokToken && conversationId) {
+    const bindPath = resolveGrokBindsPath(configDir, process.env.AGENTCHAT_GROK_BINDS);
+    if (existsSync2(bindPath)) {
+      try {
+        const parsed = parseGrokBindsText(readFileSync2(bindPath, "utf-8"));
+        binds = parsed.binds;
+        if (parsed.malformed) {
+          process.stderr.write(`[agentchat] WARNING: grok-binds file is malformed (${bindPath}); ignoring.
+`);
+        }
+      } catch {
+        binds = {};
+      }
+    }
+  }
+  const grok = decideGrokBind({
+    explicitIdentity: false,
+    hasToken: grokToken,
+    conversationId,
+    binds
+  });
+  if (grok.kind === "hit") {
+    process.stderr.write(`[agentchat] grok-bind: ${grok.conversationId} \u2192 profile "${grok.profileName}"
+`);
+    return { path: nameToPath(grok.profileName), source: "grok-bind", declaredName: grok.profileName };
+  }
+  if (grok.kind === "miss") {
+    process.stderr.write(`[agentchat] no grok-bind matched CURSOR_CONVERSATION_ID=${grok.conversationId}
+`);
+  }
   return { path: nameToPath("profile"), source: "default" };
 }
 var { path: profileFile, source: profileSource, declaredName } = resolveProfile();
@@ -2339,6 +2484,70 @@ HANDLERS.set("transcribe", async (args) => {
     return { content: [{ type: "text", text: `Error transcribing: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
   }
 });
+function loadGrokBinds() {
+  const bindPath = resolveGrokBindsPath(configDir, process.env.AGENTCHAT_GROK_BINDS);
+  if (!existsSync2(bindPath))
+    return {};
+  try {
+    return parseGrokBindsText(readFileSync2(bindPath, "utf-8")).binds;
+  } catch {
+    return {};
+  }
+}
+function applyIdentityFromProfile(newProfile, targetFile) {
+  heartbeat.stop();
+  if (backfillTimer) {
+    clearTimeout(backfillTimer);
+    backfillTimer = null;
+  }
+  if (reconnectTimer) {
+    clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+  }
+  if (ws) {
+    ws.onclose = null;
+    try {
+      ws.close();
+    } catch {}
+    ws = null;
+  }
+  sessionId = null;
+  AGENT_ID = newProfile.agent_id;
+  TOKEN = newProfile.token || "dev-token";
+  CAPABILITIES = newProfile.capabilities || ["claude-code", "coding", "chat"];
+  profile = newProfile;
+  activeProfileFile = targetFile;
+  anonymousMode = false;
+  wsReconnectAttempt = 0;
+  heartbeat.start();
+  connectWS();
+}
+function ensureGrokBoundIdentity() {
+  const boundName = boundProfileForConversation(process.env.CURSOR_CONVERSATION_ID, loadGrokBinds());
+  if (!boundName)
+    return;
+  const boundPath = nameToPath(boundName);
+  if (!existsSync2(boundPath))
+    return;
+  let boundProfile;
+  try {
+    boundProfile = JSON.parse(readFileSync2(boundPath, "utf-8"));
+  } catch {
+    return;
+  }
+  const liveName = profileNameFromPath(activeProfileFile);
+  if (!shouldHealBoundIdentity({
+    boundProfileName: boundName,
+    liveProfileName: liveName,
+    liveAgentId: AGENT_ID,
+    boundAgentId: boundProfile?.agent_id
+  })) {
+    return;
+  }
+  process.stderr.write(`[agentchat] grok-bind heal: live profile=${liveName ?? "?"} agent=${AGENT_ID || "?"} \u2192 bound "${boundName}" (${boundProfile.agent_id || "?"})
+`);
+  applyIdentityFromProfile(boundProfile, boundPath);
+}
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   let { name, arguments: args } = request.params;
   let viaExtendedCompat = false;
@@ -2348,6 +2557,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (argErr)
         return { content: [{ type: "text", text: `${name}: ${argErr}` }], isError: true };
     }
+    ensureGrokBoundIdentity();
     if (name === "list_skills") {
       const { chat_id } = args || {};
       const out = {
@@ -3444,37 +3654,21 @@ ${list}` }] };
 Available profiles:
 ${list}` }] };
       }
+      const switchGate = gateSwitchProfile({
+        conversationId: process.env.CURSOR_CONVERSATION_ID,
+        binds: loadGrokBinds(),
+        requestedProfileName: profile_name,
+        currentProfileName: profileNameFromPath(activeProfileFile)
+      });
+      if (switchGate.kind === "locked") {
+        return { content: [{ type: "text", text: switchGate.message }], isError: true };
+      }
       const targetFile = nameToPath(profile_name);
       if (!existsSync2(targetFile)) {
         return { content: [{ type: "text", text: `Profile "${profile_name}" not found. Available: ${available.join(", ")}` }], isError: true };
       }
       const newProfile = JSON.parse(readFileSync2(targetFile, "utf-8"));
-      heartbeat.stop();
-      if (backfillTimer) {
-        clearTimeout(backfillTimer);
-        backfillTimer = null;
-      }
-      if (reconnectTimer) {
-        clearTimeout(reconnectTimer);
-        reconnectTimer = null;
-      }
-      if (ws) {
-        ws.onclose = null;
-        try {
-          ws.close();
-        } catch {}
-        ws = null;
-      }
-      sessionId = null;
-      AGENT_ID = newProfile.agent_id;
-      TOKEN = newProfile.token || "dev-token";
-      CAPABILITIES = newProfile.capabilities || ["claude-code", "coding", "chat"];
-      profile = newProfile;
-      activeProfileFile = targetFile;
-      anonymousMode = false;
-      wsReconnectAttempt = 0;
-      heartbeat.start();
-      connectWS();
+      applyIdentityFromProfile(newProfile, targetFile);
       return { content: [{ type: "text", text: `Switched to profile "${profile_name}" (${AGENT_ID}). Reconnecting...` }] };
     }
     if (name === "list_channel_docs") {
@@ -3824,7 +4018,7 @@ ${list}` }] };
     return { content: [{ type: "text", text: `${name} failed: ${String(e?.message || e).slice(0, 300)}` }], isError: true };
   }
 });
-var mentionTsFile = join(configDir, `mention-ts-${AGENT_ID}.json`);
+var mentionTsFile = join2(configDir, `mention-ts-${AGENT_ID}.json`);
 function loadMentionTimestamps() {
   return loadCursor(mentionTsFile, safeStderrWrite);
 }
@@ -3832,7 +4026,7 @@ function saveMentionTimestamps(m) {
   persistCursor(mentionTsFile, m, safeStderrWrite);
 }
 var lastMentionTimestamp = loadMentionTimestamps();
-var lastSeenMessageTsFile = join(configDir, `last-seen-msg-ts-${AGENT_ID}.json`);
+var lastSeenMessageTsFile = join2(configDir, `last-seen-msg-ts-${AGENT_ID}.json`);
 function loadLastSeenMessageTs() {
   return loadCursor(lastSeenMessageTsFile, safeStderrWrite);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentschat-mcp",
   "mcpName": "io.github.swswordholy-tech/agentschat-mcp",
-  "version": "0.33.3",
+  "version": "0.33.5",
   "description": "Connect Claude Code to AgentsChat — AI Agent social network. Core tools stay lean while extended tool groups load on demand for lower token overhead and cleaner role-specific context.",
   "type": "module",
   "bin": {
@@ -67,6 +67,7 @@
     "src/timestamps.ts",
     "src/argcheck.ts",
     "src/identity.ts",
+    "src/grok-bind.ts",
     "src/terms.ts",
     "src/wake.ts",
     "src/profile-store.ts",
@@ -77,6 +78,7 @@
     "connector/identities.ts",
     "connector/server.ts",
     "connector/run.ts",
+    "connector/backfill.ts",
     "connector/README.md",
     "skills/onboarding.md",
     "dist/server.js",

package/src/grok-bind.ts

@@ -0,0 +1,193 @@
+/**
+ * Grok outbound identity bind — map CURSOR_CONVERSATION_ID (the Grok agent uuid)
+ * to an AgentsChat profile name.
+ *
+ * Pure: parse the bind map and decide whether it applies. File I/O and
+ * `nameToPath` live at the call site (`resolveProfile` in server.ts) so this
+ * stays unit-testable.
+ *
+ * Auto-bind does NOT imply AGENTCHAT_WAKE_MODE. A Cursor-tool MCP should unset
+ * WAKE_MODE because per-identity wake daemons already POST sendPrompt. If the
+ * operator set WAKE_MODE, leave it — this module never reads or writes it.
+ *
+ * Shared Cursor MCP safety: when a conversation id is bound OR the live profile
+ * is already a grok-bound identity (e.g. Cursor stdio started with `--profile Jack`
+ * and no CURSOR_CONVERSATION_ID), `switch_profile` must not steal the live
+ * identity (gateSwitchProfile). Outbound mutators should heal back to the bound
+ * profile if something already switched (shouldHealBoundIdentity).
+ */
+
+import { join } from "node:path";
+
+export const DEFAULT_GROK_BINDS_FILENAME = "grok-binds.json";
+export const GROK_BINDS_ENV = "AGENTCHAT_GROK_BINDS";
+export const CURSOR_CONVERSATION_ENV = "CURSOR_CONVERSATION_ID";
+
+/** Clear error returned when switch_profile would leave a grok-bound identity. */
+export const GROK_BIND_SWITCH_LOCKED_MESSAGE =
+  "Outbound identity is locked to grok-bind on this shared MCP; use a separate MCP process / wake daemon, do not switch_profile.";
+
+export type GrokBindDecision =
+  /** Explicit identity/token already won, or no conversation id — do not consult. */
+  | { kind: "skip" }
+  /** Conversation id present but no string profile name for it. */
+  | { kind: "miss"; conversationId: string }
+  /** Bind hit — caller resolves `<profileName>` the same way `--profile` does. */
+  | { kind: "hit"; conversationId: string; profileName: string };
+
+/** uuid → profile name. Non-string (and empty) values are ignored. */
+export function parseGrokBinds(raw: unknown): Record<string, string> {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof v !== "string") continue;
+    const name = v.trim();
+    if (!name) continue;
+    const key = k.trim();
+    if (!key) continue;
+    out[key] = name;
+  }
+  return out;
+}
+
+export function parseGrokBindsText(text: string): { binds: Record<string, string>; malformed: boolean } {
+  try {
+    return { binds: parseGrokBinds(JSON.parse(text)), malformed: false };
+  } catch {
+    return { binds: {}, malformed: true };
+  }
+}
+
+export function resolveGrokBindsPath(configDir: string, envOverride?: string): string {
+  if (envOverride && envOverride.length > 0) return envOverride;
+  return join(configDir, DEFAULT_GROK_BINDS_FILENAME);
+}
+
+/**
+ * Consult the bind map only when nothing more specific already declared identity.
+ * Explicit `--profile` / `--name` / `AGENTSCHAT_PROFILE` / `AGENTCHAT_PROFILE`
+ * and `--token` / `AGENTCHAT_TOKEN` all win.
+ */
+export function decideGrokBind(input: {
+  explicitIdentity: boolean;
+  hasToken: boolean;
+  conversationId: string | undefined;
+  binds: Record<string, string>;
+}): GrokBindDecision {
+  if (input.explicitIdentity || input.hasToken) return { kind: "skip" };
+  const id = input.conversationId?.trim();
+  if (!id) return { kind: "skip" };
+  const profileName = input.binds[id];
+  if (typeof profileName === "string" && profileName.length > 0) {
+    return { kind: "hit", conversationId: id, profileName };
+  }
+  return { kind: "miss", conversationId: id };
+}
+
+/**
+ * Bound profile name for this CURSOR_CONVERSATION_ID, or null if unbound /
+ * conversation id unset (Claude / Hermes: no lock).
+ */
+export function boundProfileForConversation(
+  conversationId: string | undefined,
+  binds: Record<string, string>,
+): string | null {
+  const id = conversationId?.trim();
+  if (!id) return null;
+  const name = binds[id];
+  return typeof name === "string" && name.length > 0 ? name : null;
+}
+
+/** Basename without `.json` — compare `activeProfileFile` to a bind name. */
+export function profileNameFromPath(profilePath: string | null | undefined): string | null {
+  if (!profilePath) return null;
+  const base = profilePath.replace(/\\/g, "/").split("/").pop() || "";
+  const name = base.replace(/\.json$/i, "");
+  return name || null;
+}
+
+export type SwitchProfileGate =
+  | { kind: "allow" }
+  | {
+      kind: "locked";
+      boundProfileName: string;
+      requestedProfileName: string;
+      message: string;
+    };
+
+/**
+ * Gate `switch_profile` when a grok outbound bind owns this MCP identity.
+ *
+ * - Empty binds → allow (Claude/Hermes with no grok-binds).
+ * - Empty / missing requested name (list profiles) → allow.
+ * - CURSOR_CONVERSATION_ID maps to a bind: lock unless requested equals that bind.
+ * - No conversation id (or unbound): if currentProfileName is one of the bind
+ *   values (Cursor stdio started with `--profile Jack`), lock unless requested
+ *   equals current — covers shared MCP without CURSOR_CONVERSATION_ID in env.
+ * - Otherwise → allow.
+ */
+export function gateSwitchProfile(input: {
+  conversationId: string | undefined;
+  binds: Record<string, string>;
+  requestedProfileName: string | undefined | null;
+  /** Basename of activeProfileFile — used when conversation id is unset. */
+  currentProfileName?: string | null;
+}): SwitchProfileGate {
+  const req =
+    typeof input.requestedProfileName === "string" ? input.requestedProfileName.trim() : "";
+  if (!req) return { kind: "allow" };
+
+  const bindValues = Object.values(input.binds).filter((v) => typeof v === "string" && v.length > 0);
+  if (bindValues.length === 0) return { kind: "allow" };
+
+  const lockedMessage = (lockedName: string) =>
+    `Outbound identity is locked to grok-bind profile "${lockedName}" on this shared MCP; ` +
+    `use a separate MCP process / wake daemon, do not switch_profile.`;
+
+  const bound = boundProfileForConversation(input.conversationId, input.binds);
+  if (bound) {
+    if (req === bound) return { kind: "allow" };
+    return {
+      kind: "locked",
+      boundProfileName: bound,
+      requestedProfileName: req,
+      message: lockedMessage(bound),
+    };
+  }
+
+  const current =
+    typeof input.currentProfileName === "string" ? input.currentProfileName.trim() : "";
+  if (current && bindValues.includes(current)) {
+    if (req === current) return { kind: "allow" };
+    return {
+      kind: "locked",
+      boundProfileName: current,
+      requestedProfileName: req,
+      message: lockedMessage(current),
+    };
+  }
+
+  return { kind: "allow" };
+}
+
+/**
+ * Whether live identity drifted from the bound profile and needs a force-reload
+ * before outbound writes (reply / other mutators that post as AGENT_ID).
+ */
+export function shouldHealBoundIdentity(input: {
+  boundProfileName: string | null;
+  liveProfileName: string | null | undefined;
+  liveAgentId: string | null | undefined;
+  boundAgentId: string | null | undefined;
+}): boolean {
+  if (!input.boundProfileName) return false;
+  if (input.liveProfileName !== input.boundProfileName) return true;
+  if (
+    typeof input.boundAgentId === "string" &&
+    input.boundAgentId.length > 0 &&
+    input.liveAgentId !== input.boundAgentId
+  ) {
+    return true;
+  }
+  return false;
+}

package/src/identity.ts

@@ -20,10 +20,13 @@
  *  - An identity WAS declared but its profile is missing → hard error. That is a
  *    typo/misconfig, and inventing an identity for it is what corrupted attribution
  *    before. Introspection never hits this branch (it passes no flags).
+ *    Grok bind (CURSOR_CONVERSATION_ID → grok-binds.json) is a declared identity
+ *    (source "grok-bind") — a hit with a missing profile file is this branch,
+ *    not a fall-through to a sibling bot.
  */
 
 /** Which resolution tier produced the profile path (see resolveProfile in server.ts). */
-export type ProfileSource = "env" | "legacy-env" | "flag-profile" | "flag-name" | "default";
+export type ProfileSource = "env" | "legacy-env" | "flag-profile" | "flag-name" | "grok-bind" | "default";
 
 export type IdentityDecision =
   /** Profile file exists — load it. */

package/src/server.ts

@@ -42,6 +42,16 @@ import { normalizeTimestampForCursor } from "./timestamps.ts";
 import { validateToolArgs } from "./argcheck.ts";
 import { decideIdentity, shouldMigrateDevToken } from "./identity.ts";
 import type { ProfileSource } from "./identity.ts";
+import {
+  decideGrokBind,
+  parseGrokBindsText,
+  resolveGrokBindsPath,
+  DEFAULT_GROK_BINDS_FILENAME,
+  boundProfileForConversation,
+  gateSwitchProfile,
+  profileNameFromPath,
+  shouldHealBoundIdentity,
+} from "./grok-bind.ts";
 import { decideTermsConsent, TERMS_URL } from "./terms.ts";
 import { fireWake, fireGrokWake, resolveGrokAgentId, resolveGrokGatewayPath, grokBearerFromGatewayConfig, grokPortFromGatewayConfig } from "./wake.ts";
 import pkg from "../package.json";
@@ -107,6 +117,13 @@ Wake a host that has no channel-notification surface (Grok Bot, generic MCP clie
                            ~/.grok/gateway.json, /home/box/sand-data/gateway.json)
   AGENTCHAT_GROK_AGENT_ID  the Grok gateway agent uuid to wake (1:1 binding)
 
+Grok multi-bot identity bind (Cursor / Grok Bot, no --profile):
+  ~/.agentschat/grok-binds.json maps CURSOR_CONVERSATION_ID (Grok uuid) → profile name.
+  AGENTCHAT_GROK_BINDS overrides that path. Profile names resolve like --profile.
+  Auto-bind does NOT set AGENTCHAT_WAKE_MODE — a Cursor-tool MCP should unset it
+  (per-identity wake daemons already POST sendPrompt). If the operator set
+  WAKE_MODE, it is left as-is.
+
 Hermes relay connector (no Hermes patch): run with --connector. See --connector --help.
 
 Identity is never created implicitly: with no --name/--profile/AGENTSCHAT_PROFILE and
@@ -124,7 +141,9 @@ const cliArgs = parseArgs();
 //   2. AGENTCHAT_PROFILE env var (legacy singular)
 //   3. --profile <name> CLI arg
 //   4. --name <name> CLI arg (also used as profile name)
-//   5. default ~/.agentschat/profile.json, falling back to ~/.agentchat/profile.json
+//   5. Grok bind: CURSOR_CONVERSATION_ID → ~/.agentschat/grok-binds.json
+//      (skipped if an explicit token is set; does NOT imply AGENTCHAT_WAKE_MODE)
+//   6. default ~/.agentschat/profile.json, falling back to ~/.agentchat/profile.json
 const homeDir = process.env.HOME || process.env.USERPROFILE || ".";
 const configDir = join(homeDir, ".agentschat");
 const legacyConfigDir = join(homeDir, ".agentchat");
@@ -148,6 +167,7 @@ function listProfileFiles(): Array<{ name: string; path: string }> {
     let files: string[] = [];
     try { files = readdirSync(dir).filter((f: string) => f.endsWith(".json")); } catch {}
     for (const file of files) {
+      if (file === DEFAULT_GROK_BINDS_FILENAME) continue; // bind map, not a profile
       const name = file.replace(/\.json$/, "");
       if (seen.has(name)) continue;
       seen.add(name);
@@ -168,7 +188,45 @@ function resolveProfile(): { path: string; source: ProfileSource; declaredName?:
   if (cliArgs.profile) return { path: nameToPath(cliArgs.profile), source: "flag-profile", declaredName: cliArgs.profile };
   // 4. --name <name>
   if (cliArgs.name) return { path: nameToPath(cliArgs.name), source: "flag-name", declaredName: cliArgs.name };
-  // 5. default — nothing was declared. NOT a licence to invent an identity.
+
+  // 5. Grok outbound bind. Explicit env/flags already returned above. An
+  // explicit --token/AGENTCHAT_TOKEN also wins: do not steal identity from
+  // operator-supplied creds. CURSOR_CONVERSATION_ID unset → skip entirely
+  // (Claude Code / Hermes: zero change). A hit with a missing profile file
+  // is a declared identity (source grok-bind) so decideIdentity hard-errors
+  // rather than falling through to a sibling bot.
+  const grokToken = !!(cliArgs.token || process.env.AGENTCHAT_TOKEN);
+  const conversationId = process.env.CURSOR_CONVERSATION_ID;
+  let binds: Record<string, string> = {};
+  if (!grokToken && conversationId) {
+    const bindPath = resolveGrokBindsPath(configDir, process.env.AGENTCHAT_GROK_BINDS);
+    if (existsSync(bindPath)) {
+      try {
+        const parsed = parseGrokBindsText(readFileSync(bindPath, "utf-8"));
+        binds = parsed.binds;
+        if (parsed.malformed) {
+          process.stderr.write(`[agentchat] WARNING: grok-binds file is malformed (${bindPath}); ignoring.\n`);
+        }
+      } catch {
+        binds = {};
+      }
+    }
+  }
+  const grok = decideGrokBind({
+    explicitIdentity: false,
+    hasToken: grokToken,
+    conversationId,
+    binds,
+  });
+  if (grok.kind === "hit") {
+    process.stderr.write(`[agentchat] grok-bind: ${grok.conversationId} → profile "${grok.profileName}"\n`);
+    return { path: nameToPath(grok.profileName), source: "grok-bind", declaredName: grok.profileName };
+  }
+  if (grok.kind === "miss") {
+    process.stderr.write(`[agentchat] no grok-bind matched CURSOR_CONVERSATION_ID=${grok.conversationId}\n`);
+  }
+
+  // 6. default — nothing was declared. NOT a licence to invent an identity.
   return { path: nameToPath("profile"), source: "default" };
 }
 
@@ -1938,6 +1996,75 @@ HANDLERS.set("transcribe", async (args) => {
   }
 });
 
+
+/** Reload grok-binds.json (or AGENTCHAT_GROK_BINDS) for runtime lock/heal checks. */
+function loadGrokBinds(): Record<string, string> {
+  const bindPath = resolveGrokBindsPath(configDir, process.env.AGENTCHAT_GROK_BINDS);
+  if (!existsSync(bindPath)) return {};
+  try {
+    return parseGrokBindsText(readFileSync(bindPath, "utf-8")).binds;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Apply a profile file as the live identity and reconnect WS.
+ * Shared by `switch_profile` and grok-bind heal.
+ */
+function applyIdentityFromProfile(newProfile: any, targetFile: string): void {
+  heartbeat.stop();
+  if (backfillTimer) { clearTimeout(backfillTimer); backfillTimer = null; }
+  if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+  if (ws) {
+    ws.onclose = null;
+    try { ws.close(); } catch {}
+    ws = null;
+  }
+  sessionId = null;
+  AGENT_ID = newProfile.agent_id;
+  TOKEN = newProfile.token || "dev-token";
+  CAPABILITIES = newProfile.capabilities || ["claude-code", "coding", "chat"];
+  profile = newProfile;
+  activeProfileFile = targetFile;
+  anonymousMode = false;
+  wsReconnectAttempt = 0;
+  heartbeat.start();
+  connectWS();
+}
+
+/**
+ * If CURSOR_CONVERSATION_ID is bound and live identity drifted (e.g. another
+ * agent called switch_profile on this shared MCP), force-reload the bound
+ * profile before outbound writes. Logs to stderr when healing.
+ */
+function ensureGrokBoundIdentity(): void {
+  const boundName = boundProfileForConversation(process.env.CURSOR_CONVERSATION_ID, loadGrokBinds());
+  if (!boundName) return;
+  const boundPath = nameToPath(boundName);
+  if (!existsSync(boundPath)) return;
+  let boundProfile: any;
+  try {
+    boundProfile = JSON.parse(readFileSync(boundPath, "utf-8"));
+  } catch {
+    return;
+  }
+  const liveName = profileNameFromPath(activeProfileFile);
+  if (!shouldHealBoundIdentity({
+    boundProfileName: boundName,
+    liveProfileName: liveName,
+    liveAgentId: AGENT_ID,
+    boundAgentId: boundProfile?.agent_id,
+  })) {
+    return;
+  }
+  process.stderr.write(
+    `[agentchat] grok-bind heal: live profile=${liveName ?? "?"} agent=${AGENT_ID || "?"} → bound "${boundName}" (${boundProfile.agent_id || "?"})\n`,
+  );
+  applyIdentityFromProfile(boundProfile, boundPath);
+}
+
+
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   let { name, arguments: args } = request.params;
   let viaExtendedCompat = false;
@@ -1954,6 +2081,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (argErr) return { content: [{ type: "text", text: `${name}: ${argErr}` }], isError: true };
     }
 
+    // Shared Cursor MCP: heal back to grok-bind identity if another agent
+    // stole the live profile via switch_profile. No-op when unbound.
+    ensureGrokBoundIdentity();
+
   if (name === "list_skills") {
     const { chat_id } = (args || {}) as { chat_id?: string };
     const out: any = {
@@ -3054,6 +3185,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return { content: [{ type: "text", text: `Current: ${current}\nAvailable profiles:\n${list}` }] };
     }
 
+    // Shared Cursor MCP: grok-binds lock outbound identity — via conversation id
+    // when set, or via current profile when Cursor stdio started with --profile
+    // and no CURSOR_CONVERSATION_ID. Refuse switches that leave the locked
+    // identity (including other Grok bots or Hermes/Spiral). No-op allowed.
+    const switchGate = gateSwitchProfile({
+      conversationId: process.env.CURSOR_CONVERSATION_ID,
+      binds: loadGrokBinds(),
+      requestedProfileName: profile_name,
+      currentProfileName: profileNameFromPath(activeProfileFile),
+    });
+    if (switchGate.kind === "locked") {
+      return { content: [{ type: "text", text: switchGate.message }], isError: true };
+    }
+
     // Find and load the profile
     const targetFile = nameToPath(profile_name);
     if (!existsSync(targetFile)) {
@@ -3061,34 +3206,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
 
     const newProfile = JSON.parse(readFileSync(targetFile, "utf-8"));
-
-    // Stop heartbeat first to prevent race with old connection
-    heartbeat.stop();
-    // Cancel any pending backfill / reconnect from the old identity.
-    if (backfillTimer) { clearTimeout(backfillTimer); backfillTimer = null; }
-    if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
-
-    // Close old connection, disable its reconnect handler
-    if (ws) {
-      ws.onclose = null;
-      try { ws.close(); } catch {}
-      ws = null;
-    }
-    sessionId = null;
-
-    // Update identity. activeProfileFile must move too — whoami reports it, and a
-    // stale value there makes the identity probe lie about which profile is live.
-    AGENT_ID = newProfile.agent_id;
-    TOKEN = newProfile.token || "dev-token";
-    CAPABILITIES = newProfile.capabilities || ["claude-code", "coding", "chat"];
-    profile = newProfile;
-    activeProfileFile = targetFile;
-    anonymousMode = false;
-
-    // Restart heartbeat and connect with new identity
-    wsReconnectAttempt = 0;
-    heartbeat.start();
-    connectWS();
+    applyIdentityFromProfile(newProfile, targetFile);
 
     return { content: [{ type: "text", text: `Switched to profile "${profile_name}" (${AGENT_ID}). Reconnecting...` }] };
   }