agentschat-mcp 0.36.5 → 0.36.7

package/dist/server.js

@@ -232,6 +232,7 @@ function shouldMigrateDevToken(i) {
 // src/grok-bind.ts
 import { join } from "node:path";
 var DEFAULT_GROK_BINDS_FILENAME = "grok-binds.json";
+var GROK_BINDS_META_FILENAME = "grok-binds.meta.json";
 function parseGrokBinds(raw) {
   if (raw === null || typeof raw !== "object" || Array.isArray(raw))
     return {};
@@ -329,6 +330,38 @@ function shouldHealBoundIdentity(input) {
   }
   return false;
 }
+var ANTIGRAVITY_WAKE_ENV = "AGENTCHAT_ANTIGRAVITY_WAKE";
+var WAKE_KIND_ENV = "AGENTCHAT_WAKE_KIND";
+var WAKE_MODE_ENV = "AGENTCHAT_WAKE_MODE";
+function nonGrokWakeReason(env) {
+  const anti = (env[ANTIGRAVITY_WAKE_ENV] ?? "").trim();
+  if (anti)
+    return `${ANTIGRAVITY_WAKE_ENV}=${anti}`;
+  const kind = (env[WAKE_KIND_ENV] ?? "").trim();
+  if (kind && kind.toLowerCase() !== "grok")
+    return `${WAKE_KIND_ENV}=${kind}`;
+  const mode = (env[WAKE_MODE_ENV] ?? "").trim();
+  if (mode && mode.toLowerCase() !== "grok")
+    return `${WAKE_MODE_ENV}=${mode}`;
+  return null;
+}
+function grokBindApplies(input) {
+  const reason = nonGrokWakeReason(input.env);
+  if (reason)
+    return { applies: false, reason: `non-grok wake (${reason})` };
+  const explicit = typeof input.explicitProfileName === "string" ? profileNameFromPath(input.explicitProfileName.trim()) : null;
+  if (explicit) {
+    const bound = boundProfileForConversation(input.conversationId, input.binds);
+    const norm = (n) => n.replace(/[^a-zA-Z0-9_-]/g, "_");
+    if (bound && norm(bound) !== norm(explicit)) {
+      return {
+        applies: false,
+        reason: `explicit profile "${explicit}" differs from grok-bind profile "${bound}"`
+      };
+    }
+  }
+  return { applies: true };
+}
 
 // src/terms.ts
 var TERMS_URL = "https://agents-chat.com/terms";
@@ -593,13 +626,14 @@ async function fireGrokWake(msg, cfg) {
 var package_default = {
   name: "agentschat-mcp",
   mcpName: "io.github.swswordholy-tech/agentschat-mcp",
-  version: "0.36.5",
+  version: "0.36.7",
   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: {
     "agentschat-mcp": "src/cli.mjs",
     "agentchat-mcp": "src/cli.mjs",
-    "agentschat-ensure-grok-wakes": "scripts/ensure-grok-wakes.mjs"
+    "agentschat-ensure-grok-wakes": "scripts/ensure-grok-wakes.mjs",
+    "agentschat-grok-bind-register": "scripts/grok-bind-register.sh"
   },
   engines: {
     node: ">=22",
@@ -665,6 +699,7 @@ var package_default = {
     "src/identity.ts",
     "src/grok-bind.ts",
     "src/tool-annotations.ts",
+    "src/identity-guard.ts",
     "src/terms.ts",
     "src/wake.ts",
     "src/profile-store.ts",
@@ -683,6 +718,7 @@ var package_default = {
     "dist/server.js",
     "dist/connector.js",
     "scripts/ensure-grok-wakes.mjs",
+    "scripts/grok-bind-register.sh",
     "README.md",
     "CHANGELOG.md",
     "codex/",
@@ -736,6 +772,70 @@ function safeWriteProfile(path, data, warn = defaultWarn) {
   }
 }
 
+// src/identity-guard.ts
+var IDENTITY_GUARD_FILENAME = "identity-guard.json";
+function emptyGuardRecord() {
+  return { bySelector: {}, lastEffective: null };
+}
+function parseGuardRecord(text) {
+  if (!text)
+    return emptyGuardRecord();
+  try {
+    const raw = JSON.parse(text);
+    if (!raw || typeof raw !== "object")
+      return emptyGuardRecord();
+    return {
+      bySelector: raw.bySelector && typeof raw.bySelector === "object" ? { ...raw.bySelector } : {},
+      lastEffective: raw.lastEffective && typeof raw.lastEffective.agentId === "string" ? {
+        agentId: raw.lastEffective.agentId,
+        source: String(raw.lastEffective.source ?? "unknown"),
+        ...raw.lastEffective.declaredName ? { declaredName: String(raw.lastEffective.declaredName) } : {},
+        ts: String(raw.lastEffective.ts ?? "")
+      } : null
+    };
+  } catch {
+    return emptyGuardRecord();
+  }
+}
+function decideIdentityGuard(prev, current) {
+  if (!current.agentId)
+    return { kind: "ok" };
+  const last = prev.lastEffective;
+  if (!last)
+    return { kind: "ok" };
+  if (last.agentId === current.agentId)
+    return { kind: "ok" };
+  if (current.source === "default") {
+    return {
+      kind: "gate",
+      message: `IDENTITY CHANGED after reconnect/restart: previously trusted as "${last.agentId}" ` + `(via ${last.source}${last.declaredName ? ` "${last.declaredName}"` : ""}), but this boot resolved the DEFAULT profile ` + `"${current.agentId}". Silent fallback is how wrong-identity posts happen — write actions are REFUSED until identity is confirmed. ` + `Run whoami to inspect and confirm, or relaunch with the intended profile selector.`
+    };
+  }
+  if (current.declaredName && prev.bySelector[current.declaredName] && prev.bySelector[current.declaredName] !== current.agentId) {
+    return {
+      kind: "warn",
+      message: `identity for selector "${current.declaredName}" changed: was "${prev.bySelector[current.declaredName]}", ` + `now "${current.agentId}". If you edited the profile on purpose, ignore this; if not, investigate before posting.`
+    };
+  }
+  return { kind: "ok" };
+}
+function advanceGuardRecord(prev, current, ts, trusted) {
+  const next = { bySelector: { ...prev.bySelector }, lastEffective: prev.lastEffective };
+  if (!current.agentId)
+    return next;
+  if (current.declaredName)
+    next.bySelector[current.declaredName] = current.agentId;
+  if (trusted) {
+    next.lastEffective = {
+      agentId: current.agentId,
+      source: current.source,
+      ...current.declaredName ? { declaredName: current.declaredName } : {},
+      ts
+    };
+  }
+  return next;
+}
+
 // src/read-cursor.ts
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
 function loadCursor(file, warn) {
@@ -974,7 +1074,7 @@ function listProfileFiles() {
       files = readdirSync(dir).filter((f) => f.endsWith(".json"));
     } catch {}
     for (const file of files) {
-      if (file === DEFAULT_GROK_BINDS_FILENAME)
+      if (file === DEFAULT_GROK_BINDS_FILENAME || file === GROK_BINDS_META_FILENAME)
         continue;
       const name = file.replace(/\.json$/, "");
       if (seen.has(name))
@@ -995,7 +1095,12 @@ function resolveProfile() {
   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;
+  const nonGrokWake = nonGrokWakeReason(process.env);
+  const conversationId = nonGrokWake ? undefined : process.env.CURSOR_CONVERSATION_ID;
+  if (nonGrokWake && process.env.CURSOR_CONVERSATION_ID) {
+    process.stderr.write(`[agentchat] grok-bind skipped: non-grok wake (${nonGrokWake})
+`);
+  }
   let binds = {};
   if (!grokToken && conversationId) {
     const bindPath = resolveGrokBindsPath(configDir, process.env.AGENTCHAT_GROK_BINDS);
@@ -1246,6 +1351,54 @@ if (!anonymousMode || explicitAgentId !== undefined || hasToken) {
     process.exit(1);
   }
 }
+var identityGateMessage = "";
+var identityGuardFile = join2(configDir, IDENTITY_GUARD_FILENAME);
+function persistGuardRecord(rec) {
+  try {
+    mkdirSync(configDir, { recursive: true });
+    safeWriteProfile(identityGuardFile, rec);
+  } catch {}
+}
+function confirmLiveIdentityTrusted() {
+  identityGateMessage = "";
+  const live = {
+    agentId: AGENT_ID,
+    source: identity.mode === "env-creds" ? "env-creds" : profileSource,
+    ...declaredName ? { declaredName } : {}
+  };
+  guardRecord = advanceGuardRecord(guardRecord, live, new Date().toISOString(), true);
+  persistGuardRecord(guardRecord);
+}
+var guardRecord = (() => {
+  try {
+    return parseGuardRecord(readFileSync3(identityGuardFile, "utf-8"));
+  } catch {
+    return emptyGuardRecord();
+  }
+})();
+var guardBootIdentity = {
+  agentId: AGENT_ID,
+  source: identity.mode === "env-creds" ? "env-creds" : profileSource,
+  ...declaredName ? { declaredName } : {}
+};
+{
+  const verdict = AGENT_ID ? decideIdentityGuard(guardRecord, guardBootIdentity) : { kind: "ok" };
+  if (verdict.kind === "gate") {
+    identityGateMessage = verdict.message;
+    process.stderr.write(`
+[agentchat] \uD83D\uDEA8 ${verdict.message}
+
+`);
+    guardRecord = advanceGuardRecord(guardRecord, guardBootIdentity, new Date().toISOString(), false);
+  } else {
+    if (verdict.kind === "warn")
+      process.stderr.write(`[agentchat] WARNING: ${verdict.message}
+`);
+    guardRecord = advanceGuardRecord(guardRecord, guardBootIdentity, new Date().toISOString(), true);
+  }
+  if (AGENT_ID)
+    persistGuardRecord(guardRecord);
+}
 if (cliArgs.name && profile.display_name !== cliArgs.name) {
   profile.display_name = cliArgs.name;
 }
@@ -2702,6 +2855,15 @@ function loadGrokBinds() {
     return {};
   }
 }
+var explicitStartupProfileName = profileSource === "env" || profileSource === "legacy-env" || profileSource === "flag-profile" || profileSource === "flag-name" ? declaredName ?? null : null;
+function currentGrokBindApplicability(binds) {
+  return grokBindApplies({
+    env: process.env,
+    explicitProfileName: explicitStartupProfileName,
+    conversationId: process.env.CURSOR_CONVERSATION_ID,
+    binds
+  });
+}
 function applyIdentityFromProfile(newProfile, targetFile) {
   validateIdentityProfile(newProfile, targetFile);
   heartbeat.stop();
@@ -2727,6 +2889,8 @@ function applyIdentityFromProfile(newProfile, targetFile) {
   profile = newProfile;
   activeProfileFile = targetFile;
   anonymousMode = false;
+  guardRecord = advanceGuardRecord(guardRecord, { agentId: AGENT_ID, source: "switch_profile", ...profileNameFromPath(targetFile) ? { declaredName: profileNameFromPath(targetFile) } : {} }, new Date().toISOString(), true);
+  persistGuardRecord(guardRecord);
   wsReconnectAttempt = 0;
   heartbeat.start();
   connectWS();
@@ -2734,7 +2898,10 @@ function applyIdentityFromProfile(newProfile, targetFile) {
 function ensureGrokBoundIdentity() {
   if (profileSource !== "grok-bind" || hasToken || cliArgs.id || process.env.AGENTCHAT_AGENT_ID)
     return;
-  const boundName = boundProfileForConversation(process.env.CURSOR_CONVERSATION_ID, loadGrokBinds());
+  const healBinds = loadGrokBinds();
+  if (!currentGrokBindApplicability(healBinds).applies)
+    return;
+  const boundName = boundProfileForConversation(process.env.CURSOR_CONVERSATION_ID, healBinds);
   if (!boundName)
     return;
   const boundPath = nameToPath(boundName);
@@ -2769,6 +2936,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return { content: [{ type: "text", text: `${name}: ${argErr}` }], isError: true };
     }
     ensureGrokBoundIdentity();
+    if (identityGateMessage && name !== "whoami" && TOOL_ANNOTATIONS[name]?.readOnlyHint !== true) {
+      return { content: [{ type: "text", text: `\uD83D\uDEA8 ${identityGateMessage}` }], isError: true };
+    }
     if (name === "list_skills") {
       const { chat_id } = args || {};
       const out = {
@@ -3675,7 +3845,12 @@ ${brief}` }] };
           authLine = "REST auth: unknown";
         }
       }
-      return { content: [{ type: "text", text: `Profile: ${profile.display_name || AGENT_ID}
+      const gateNotice = identityGateMessage ? `\uD83D\uDEA8 IDENTITY GUARD: ${identityGateMessage}
+(This whoami call confirms identity \u2014 writes are now unblocked. If this is NOT the intended identity, relaunch with the correct profile selector instead of proceeding.)
+
+` : "";
+      const wasGated = identityGateMessage !== "";
+      const text = `Profile: ${profile.display_name || AGENT_ID}
 Agent ID: ${AGENT_ID}
 Server: ${REST_URL}
 Web chat: ${REST_URL}/chat/${encodeURIComponent(AGENT_ID)}
@@ -3686,7 +3861,10 @@ ${authLine}
 ${claimedLine}${claimHint ? `
 ${claimHint}` : ""}
 Capabilities: ${CAPABILITIES.join(", ")}
-Profile file: ${activeProfileFile ?? (anonymousMode ? "(none \u2014 anonymous, no profile written)" : "(none \u2014 credentials from environment)")}` }] };
+Profile file: ${activeProfileFile ?? (anonymousMode ? "(none \u2014 anonymous, no profile written)" : "(none \u2014 credentials from environment)")}`;
+      if (wasGated)
+        confirmLiveIdentityTrusted();
+      return { content: [{ type: "text", text: gateNotice + text }] };
     }
     if (name === "list_channels") {
       const { limit = 50 } = args;
@@ -3858,9 +4036,11 @@ ${list}` }] };
 Available profiles:
 ${list}` }] };
       }
-      const switchGate = gateSwitchProfile({
+      const switchBinds = loadGrokBinds();
+      const bindApplies = currentGrokBindApplicability(switchBinds);
+      const switchGate = !bindApplies.applies ? { kind: "allow" } : gateSwitchProfile({
         conversationId: process.env.CURSOR_CONVERSATION_ID,
-        binds: loadGrokBinds(),
+        binds: switchBinds,
         requestedProfileName: profile_name,
         currentProfileName: profileNameFromPath(activeProfileFile)
       });

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "agentschat-mcp",
   "mcpName": "io.github.swswordholy-tech/agentschat-mcp",
-  "version": "0.36.5",
+  "version": "0.36.7",
   "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": {
     "agentschat-mcp": "src/cli.mjs",
     "agentchat-mcp": "src/cli.mjs",
-    "agentschat-ensure-grok-wakes": "scripts/ensure-grok-wakes.mjs"
+    "agentschat-ensure-grok-wakes": "scripts/ensure-grok-wakes.mjs",
+    "agentschat-grok-bind-register": "scripts/grok-bind-register.sh"
   },
   "engines": {
     "node": ">=22",
@@ -73,6 +74,7 @@
     "src/identity.ts",
     "src/grok-bind.ts",
     "src/tool-annotations.ts",
+    "src/identity-guard.ts",
     "src/terms.ts",
     "src/wake.ts",
     "src/profile-store.ts",
@@ -91,6 +93,7 @@
     "dist/server.js",
     "dist/connector.js",
     "scripts/ensure-grok-wakes.mjs",
+    "scripts/grok-bind-register.sh",
     "README.md",
     "CHANGELOG.md",
     "codex/",

package/scripts/ensure-grok-wakes.mjs

@@ -11,10 +11,15 @@
  *   AGENTCHAT_WAKE_MODE=grok AGENTCHAT_GROK_AGENT_ID=<uuid> AGENTCHAT_NO_PROXY=1 \
  *     <agentschat-mcp> --profile <profileName>
  *
- * After starts (or when binds are empty), prunes any AGENTCHAT_WAKE_MODE=grok
- * process whose AGENTCHAT_GROK_AGENT_ID is not a binds key AND whose --profile
- * is not a binds value. Never kills processes without WAKE_MODE=grok (outbound
- * Cursor MCP).
+ * After starts, prunes any AGENTCHAT_WAKE_MODE=grok process whose
+ * AGENTCHAT_GROK_AGENT_ID is not a binds key AND whose --profile is not a binds
+ * value. A MISSING binds file prunes nothing (only an existing file — even `{}` —
+ * is authoritative). Every prune is logged with its reason. Never kills processes
+ * without WAKE_MODE=grok (outbound Cursor MCP).
+ *
+ * This script NEVER writes the binds file. Each Grok bot registers itself with
+ * `grok-bind-register.sh <profile>` (the only writer; see shouldPruneBindEntry for
+ * its `--prune` rules). No hard-coded bot list.
  *
  * Prints already-up|started|stopped|failed lines. Exit 0 if no failures.
  * Never prints tokens.
@@ -45,6 +50,46 @@ export function parseBinds(raw) {
   return out;
 }
 
+/** Real Grok agent uuid (rejects `sand-subagent-*` and other non-UUID ids). */
+export const AGENT_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** @param {string | undefined | null} id */
+export function isRealAgentUuid(id) {
+  return typeof id === "string" && AGENT_UUID_RE.test(id.trim());
+}
+
+export const BIND_PRUNE_MAX_AGE_DAYS = 7;
+
+/**
+ * Bind-entry prune rule used by grok-bind-register.sh --prune (the only writer).
+ * Returns a reason string when the entry should be removed, else null:
+ *  - its profile file is gone, OR
+ *  - the agent's data dir is missing AND its last registration is older than
+ *    maxAgeDays. Entries with no recorded registration are never age-pruned.
+ * @param {{ profileExists: boolean, agentDirExists: boolean, lastRegisteredEpoch?: number | null, nowEpoch: number, maxAgeDays?: number }} i
+ * @returns {string | null}
+ */
+export function shouldPruneBindEntry(i) {
+  if (!i.profileExists) return "profile file missing";
+  const maxAge = (i.maxAgeDays ?? BIND_PRUNE_MAX_AGE_DAYS) * 86400;
+  if (
+    !i.agentDirExists &&
+    typeof i.lastRegisteredEpoch === "number" &&
+    i.nowEpoch - i.lastRegisteredEpoch > maxAge
+  ) {
+    return "agent dir missing and last registration too old";
+  }
+  return null;
+}
+
+/**
+ * Whether orphan-wake pruning may run at all: only when the binds file exists.
+ * @param {boolean} bindsFileExists
+ */
+export function mayPruneWakes(bindsFileExists) {
+  return bindsFileExists === true;
+}
+
 /** @param {string} text */
 export function parseBindsText(text) {
   try {
@@ -366,22 +411,26 @@ async function main() {
     }
   }
 
-  if (entries.length === 0) {
-    console.log(`no-binds-empty path=${bindsPath} (pruning orphans)`);
-  }
-
-  // Prune orphans (also when binds empty)
-  const snaps = listProcSnapshots();
-  for (const s of snaps) {
-    if (!shouldPruneWake(s.environ, s.cmdline, binds)) continue;
-    if (stopWakePid(s.pid)) {
-      console.log(`stopped orphan pid=${s.pid}`);
-      stopped++;
+  const bindsExist = existsSync(bindsPath);
+  if (!mayPruneWakes(bindsExist)) {
+    console.log(`no-binds path=${bindsPath} (missing file: pruning nothing)`);
+  } else {
+    if (entries.length === 0) {
+      console.log(`no-binds-empty path=${bindsPath} (pruning orphans)`);
+    }
+    // Prune orphans — logged one line per stopped process with its reason.
+    const snaps = listProcSnapshots();
+    for (const s of snaps) {
+      if (!shouldPruneWake(s.environ, s.cmdline, binds)) continue;
+      const profile = profileFromCmdline(s.cmdline) || "?";
+      const agentId = agentIdFromEnviron(s.environ) || "?";
+      if (stopWakePid(s.pid)) {
+        console.log(
+          `stopped orphan pid=${s.pid} profile=${profile} agent_id=${agentId} ts=${new Date().toISOString()} reason=not-in-binds path=${bindsPath}`,
+        );
+        stopped++;
+      }
     }
-  }
-
-  if (stopped === 0 && entries.length === 0 && !existsSync(bindsPath)) {
-    /* already logged no-binds */
   }
 
   process.exit(failed > 0 ? 1 : 0);

package/scripts/example-url-wake-ensure.sh

@@ -23,6 +23,15 @@
 #   AGENTCHAT_NO_PROXY=1
 #   unset AGENTCHAT_WAKE_MODE
 #
+# Start non-Grok stacks with the Cursor session env REMOVED — a shell spawned by
+# a Grok agent carries that agent's CURSOR_CONVERSATION_ID, which must not leak
+# into this host (grok-bind would treat it as the Grok bot). e.g. at the top of
+# each start/ensure script (CURSOR_AGENT_STORE_* computed dynamically):
+#   u=$(awk 'BEGIN{for(k in ENVIRON) if(k ~ /^CURSOR_AGENT_STORE_/) printf "-u %s ", k}')
+#   exec env -u CURSOR_CONVERSATION_ID -u CURSOR_REQUEST_ID -u __CURSOR_SANDBOX_ENV_RESTORE -u CURSOR_AGENT $u sh "$0" "$@"
+#   (guard so it only re-execs while one of those keys is still set)
+# Never do this for Grok WAKE_MODE=grok wakes — they need their own id.
+#
 # Suggested start-mcp-wake shape:
 #   setsid -f env AGENTCHAT_WAKE_KIND=url \
 #     sh -c 'set -a; . wake.env; set +a; unset AGENTCHAT_WAKE_MODE;

package/scripts/example-url-wake-receiver.mjs

@@ -86,6 +86,27 @@ function sendJson(res, status, obj) {
   res.end(body);
 }
 
+/**
+ * Cursor session env that must not leak into a non-Grok host turn (or its
+ * AgentsChat MCP child): e.g. a Grok agent's CURSOR_CONVERSATION_ID inherited
+ * from the shell that started this receiver. CURSOR_AGENT_STORE_* is dropped too.
+ */
+export const LEAKED_CURSOR_ENV = [
+  "CURSOR_CONVERSATION_ID",
+  "CURSOR_REQUEST_ID",
+  "__CURSOR_SANDBOX_ENV_RESTORE",
+  "CURSOR_AGENT",
+];
+
+/** Copy of `base` without leaked Cursor session keys. Does not mutate `base`. */
+export function withoutCursorSessionEnv(base) {
+  const out = { ...base };
+  for (const k of Object.keys(out)) {
+    if (LEAKED_CURSOR_ENV.includes(k) || k.startsWith("CURSOR_AGENT_STORE_")) delete out[k];
+  }
+  return out;
+}
+
 /** Build a prompt string hosts can inject into one dedicated session. */
 export function buildHostPrompt(job) {
   const mentioned = Array.isArray(job.mentioned_ids)
@@ -217,7 +238,7 @@ function startServer() {
       const child = spawn(cmd, {
         shell: true,
         env: {
-          ...process.env,
+          ...withoutCursorSessionEnv(process.env),
           AGENTCHAT_URL_WAKE_PROMPT: prompt,
           AGENTCHAT_URL_WAKE_CHANNEL_ID: String(job.channel_id || ""),
           AGENTCHAT_URL_WAKE_MESSAGE_ID: String(job.message_id || ""),

package/scripts/grok-bind-register.sh

@@ -0,0 +1,159 @@
+#!/bin/sh
+# grok-bind-register.sh — the ONLY writer of grok-binds.json.
+#
+#   grok-bind-register.sh <profile>   register the CALLER (own CURSOR_CONVERSATION_ID) as <profile>
+#   grok-bind-register.sh --prune     drop stale entries (see rules below); logs every prune
+#
+# Each Grok bot registers itself; there is no hard-coded bot list. A machine's
+# binds file therefore only contains the Grok bots actually started there.
+#
+# Register rules:
+#   - own uuid = $CURSOR_CONVERSATION_ID, must be a real UUID (sand-subagent-* etc. rejected)
+#   - <profile> must be [A-Za-z0-9_-]+ and $AGENTSCHAT_DIR/<profile>.json must exist
+#   - flock grok-binds.json.lock; set ONLY own key; write temp + rename; mode 600
+#   - sidecar grok-binds.meta.json records {profile, registered_by, ts} per uuid
+#     (grok-binds.json itself stays a plain {uuid: profile} map)
+# Prune rules (an entry is removed only if):
+#   - its profile file $AGENTSCHAT_DIR/<profile>.json is gone, OR
+#   - $AGENT_DATA_DIR/<uuid> is missing AND its last registration (meta ts) is > 7 days old
+#   Missing binds file → nothing to prune. Entries without meta ts are never age-pruned.
+# Never prints tokens.
+set -eu
+
+AGENTSCHAT_DIR="${AGENTSCHAT_DIR:-${HOME:-/home/box}/.agentschat}"
+BINDS="${AGENTCHAT_GROK_BINDS:-$AGENTSCHAT_DIR/grok-binds.json}"
+META="${BINDS%.json}.meta.json"
+LOCK="$BINDS.lock"
+AGENT_DATA_DIR="${AGENT_DATA_DIR:-${HOME:-/home/box}/agent-data/agents}"
+PRUNE_AGE_DAYS="${GROK_BIND_PRUNE_AGE_DAYS:-7}"
+PRUNE_LOG="${GROK_BIND_PRUNE_LOG:-$AGENTSCHAT_DIR/grok-binds.prune.log}"
+
+usage() { echo "usage: $0 <profile> | --prune" >&2; exit 2; }
+[ $# -eq 1 ] || usage
+
+mode=register
+profile=""
+case "$1" in
+  --prune) mode=prune ;;
+  -h|--help) usage ;;
+  -*) usage ;;
+  *) profile="$1" ;;
+esac
+
+uuid=""
+if [ "$mode" = register ]; then
+  case "$profile" in
+    *[!A-Za-z0-9_-]*|"") echo "grok-bind-register: invalid profile name '$profile'" >&2; exit 2 ;;
+  esac
+  uuid="${CURSOR_CONVERSATION_ID:-}"
+  if ! printf '%s' "$uuid" | grep -Eqi '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'; then
+    echo "grok-bind-register: CURSOR_CONVERSATION_ID is not a real agent UUID ('${uuid:-<empty>}'); refusing (subagents must not register)" >&2
+    exit 3
+  fi
+  if [ ! -f "$AGENTSCHAT_DIR/$profile.json" ]; then
+    echo "grok-bind-register: missing profile file $AGENTSCHAT_DIR/$profile.json; refusing" >&2
+    exit 4
+  fi
+fi
+
+mkdir -p "$(dirname "$BINDS")"
+exec 9>>"$LOCK"
+if ! flock -w 15 9; then
+  echo "grok-bind-register: could not lock $LOCK" >&2
+  exit 5
+fi
+
+MODE="$mode" UUID="$uuid" PROFILE="$profile" BINDS="$BINDS" META="$META" \
+AGENTSCHAT_DIR="$AGENTSCHAT_DIR" AGENT_DATA_DIR="$AGENT_DATA_DIR" \
+PRUNE_AGE_DAYS="$PRUNE_AGE_DAYS" PRUNE_LOG="$PRUNE_LOG" python3 - <<'PY'
+import json, os, socket, sys, tempfile, time
+from datetime import datetime, timezone
+
+mode = os.environ["MODE"]; binds_p = os.environ["BINDS"]; meta_p = os.environ["META"]
+adir = os.environ["AGENTSCHAT_DIR"]; data_dir = os.environ["AGENT_DATA_DIR"]
+age_days = float(os.environ["PRUNE_AGE_DAYS"]); prune_log = os.environ["PRUNE_LOG"]
+
+def load(p):
+    try:
+        with open(p) as f:
+            d = json.load(f)
+        return d if isinstance(d, dict) else None
+    except FileNotFoundError:
+        return {}
+    except Exception:
+        return None
+
+def write(p, d):
+    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(p) or ".", prefix="." + os.path.basename(p) + ".")
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(d, f, indent=2); f.write("\n")
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, p)
+    except Exception:
+        try: os.unlink(tmp)
+        except Exception: pass
+        raise
+
+def now_iso():
+    return datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds")
+
+def log_prune(msg):
+    line = f"{now_iso()} prune {msg}"
+    print(line)
+    try:
+        with open(prune_log, "a") as f:
+            f.write(line + "\n")
+        os.chmod(prune_log, 0o600)
+    except Exception:
+        pass
+
+if mode == "register":
+    uuid = os.environ["UUID"]; profile = os.environ["PROFILE"]
+    binds = load(binds_p)
+    if binds is None:
+        print(f"grok-bind-register: {binds_p} is malformed; refusing to overwrite", file=sys.stderr); sys.exit(6)
+    meta = load(meta_p) or {}
+    prev = binds.get(uuid)
+    if prev != profile:
+        binds[uuid] = profile
+        write(binds_p, binds)
+    else:
+        os.chmod(binds_p, 0o600)
+    meta[uuid] = {"profile": profile,
+                  "registered_by": f"{uuid}@{socket.gethostname()}",
+                  "ts": now_iso(), "epoch": int(time.time())}
+    write(meta_p, meta)
+    action = "refreshed" if prev == profile else (f"rebound(from {prev})" if prev else "registered")
+    print(f"grok-bind-register: {action} {uuid} -> {profile}")
+    sys.exit(0)
+
+# prune
+if not os.path.exists(binds_p):
+    print(f"grok-bind-register: no binds file {binds_p}; nothing to prune"); sys.exit(0)
+binds = load(binds_p)
+if binds is None:
+    print(f"grok-bind-register: {binds_p} is malformed; not pruning", file=sys.stderr); sys.exit(6)
+meta = load(meta_p) or {}
+now = time.time(); removed = []
+for uuid, profile in list(binds.items()):
+    reason = None
+    if not isinstance(profile, str) or not profile.strip():
+        continue
+    if not os.path.exists(os.path.join(adir, f"{profile}.json")):
+        reason = f"profile file {profile}.json missing"
+    else:
+        m = meta.get(uuid) if isinstance(meta.get(uuid), dict) else None
+        epoch = m.get("epoch") if m else None
+        if not os.path.isdir(os.path.join(data_dir, uuid)) and isinstance(epoch, (int, float)) \
+                and now - epoch > age_days * 86400:
+            reason = f"agent dir missing and last registration {m.get('ts')} older than {age_days:g}d"
+    if reason:
+        removed.append(uuid)
+        log_prune(f"uuid={uuid} profile={profile} reason={reason}")
+if removed:
+    for u in removed:
+        binds.pop(u, None); meta.pop(u, None)
+    write(binds_p, binds); write(meta_p, meta)
+print(f"grok-bind-register: prune done removed={len(removed)} kept={len(binds)}")
+PY