agentschat-mcp 0.29.0 → 0.30.0

package/src/server.ts

@@ -4,16 +4,14 @@
  * 像 weixin 插件一样：WebSocket 消息 → MCP channel notification → Claude Code 对话
  */
 
-// Runtime guard: this plugin ships its TypeScript entrypoint directly and
-// relies on Bun's global WebSocket, so it must run under Bun (launch via
-// `bunx agentschat-mcp`, not npx/node). Fail fast with a clear message rather
-// than a cryptic parse/"WebSocket is not defined" error downstream.
-if (typeof (globalThis as any).Bun === "undefined") {
-  process.stderr.write(
-    "[agentchat] agentschat-mcp requires the Bun runtime. Install Bun (https://bun.sh) and launch with `bunx agentschat-mcp` (not npx/node).\n",
-  );
-  process.exit(1);
-}
+// Runtime: Bun is the primary/first-class runtime (`bunx agentschat-mcp` runs
+// this .ts source directly, no build step). It ALSO runs on plain Node via the
+// prebuilt bundle in dist/ (see src/cli.mjs launcher) so directory/registry
+// tooling that introspects over stdio with Node/npx (e.g. Glama) can install
+// and list tools. All Bun-specific I/O was replaced with node:fs; the WebSocket
+// connect is wrapped in try/catch, so a missing global WebSocket (older Node)
+// degrades to a reconnect log rather than crashing stdio/tools-list. Node 22+
+// (global WebSocket/fetch/FormData) gets full functionality.
 
 // ── Proxy bypass ──────────────────────────────────────────────────
 // MCP subprocess inherits the parent's HTTP_PROXY/HTTPS_PROXY which
@@ -42,6 +40,8 @@ import { messageDedupKey, MessageDedup } from "./dedup.ts";
 import { computeReconnectDelay } from "./reconnect.ts";
 import { normalizeTimestampForCursor } from "./timestamps.ts";
 import { validateToolArgs } from "./argcheck.ts";
+import { decideIdentity, shouldMigrateDevToken } from "./identity.ts";
+import type { ProfileSource } from "./identity.ts";
 import pkg from "../package.json";
 import {
   CallToolRequestSchema,
@@ -49,16 +49,13 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 // --- Config: CLI args > env vars > profile file > defaults ---
-import { readFileSync, existsSync, writeFileSync, mkdirSync, renameSync, chmodSync, readdirSync } from "fs";
+import { readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync } from "fs";
 import { join, dirname } from "path";
-
-/** Atomic write: write to .tmp then rename (prevents corrupted profile on crash) */
-function safeWriteProfile(path: string, data: any) {
-  const tmp = path + ".tmp";
-  writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
-  renameSync(tmp, path);
-  try { chmodSync(path, 0o600); } catch {}
-}
+// Atomic + 0600-by-construction profile writer. Lives in its own module so the
+// "the key is never world-readable, even mid-write" property is directly testable.
+import { safeWriteProfile } from "./profile-store.ts";
+// Read-cursor persistence: a state change that merely *lives* in the teardown path.
+import { flushCursor, loadCursor, persistCursor } from "./read-cursor.ts";
 import { randomUUID } from "crypto";
 
 function parseArgs() {
@@ -71,6 +68,8 @@ function parseArgs() {
     else if (args[i] === "--token" && args[i + 1]) parsed.token = args[++i];
     else if (args[i] === "--caps" && args[i + 1]) parsed.caps = args[++i];
     else if (args[i] === "--profile" && args[i + 1]) parsed.profile = args[++i];
+    // Boolean flag: explicit opt-in to creating a NEW account (see src/identity.ts).
+    else if (args[i] === "--register") parsed.register = "1";
   }
   return parsed;
 }
@@ -82,14 +81,19 @@ Usage: claude mcp add agentschat -- npx agentschat-mcp [options]
        claude --dangerously-load-development-channels server:agentschat
 
 Options:
-  --name <name>      Display name (also used as profile name)
+  --name <name>      Display name (also used as profile name). Registers a NEW agent
+                     if no profile exists for it.
   --profile <name>   Use specific profile (~/.agentschat/<name>.json, falls back to ~/.agentchat)
+  --register         Explicitly opt in to registering a new agent (implied by --name)
   --id <id>          Agent ID (default: auto-generated)
   --url <url>        Server URL (default: production)
-  --token <token>    Auth token (default: auto-registered)
+  --token <token>    Auth token (skips registration entirely)
   --caps <a,b,c>     Capabilities (comma-separated)
   -h, --help         Show this help
 
+Identity is never created implicitly: with no --name/--profile/AGENTSCHAT_PROFILE and
+no token, the server runs ANONYMOUS (lists tools, but never registers an account).
+
 Profiles stored in: ~/.agentschat/ (legacy fallback: ~/.agentchat/)
 Docs: https://github.com/swswordholy-tech/AgentsChatProtocol`);
   process.exit(0);
@@ -135,20 +139,30 @@ function listProfileFiles(): Array<{ name: string; path: string }> {
   return profiles;
 }
 
-function resolveProfilePath(): string {
+function resolveProfile(): { path: string; source: ProfileSource; declaredName?: string } {
   // 1. AGENTSCHAT_PROFILE env var (supports both name and full path)
-  if (process.env.AGENTSCHAT_PROFILE) return nameToPath(process.env.AGENTSCHAT_PROFILE);
+  if (process.env.AGENTSCHAT_PROFILE)
+    return { path: nameToPath(process.env.AGENTSCHAT_PROFILE), source: "env", declaredName: process.env.AGENTSCHAT_PROFILE };
   // 2. AGENTCHAT_PROFILE env var (legacy alias)
-  if (process.env.AGENTCHAT_PROFILE) return nameToPath(process.env.AGENTCHAT_PROFILE);
+  if (process.env.AGENTCHAT_PROFILE)
+    return { path: nameToPath(process.env.AGENTCHAT_PROFILE), source: "legacy-env", declaredName: process.env.AGENTCHAT_PROFILE };
   // 3. --profile <name>
-  if (cliArgs.profile) return nameToPath(cliArgs.profile);
+  if (cliArgs.profile) return { path: nameToPath(cliArgs.profile), source: "flag-profile", declaredName: cliArgs.profile };
   // 4. --name <name>
-  if (cliArgs.name) return nameToPath(cliArgs.name);
-  // 5. default
-  return nameToPath("profile");
+  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.
+  return { path: nameToPath("profile"), source: "default" };
 }
 
-const profileFile = resolveProfilePath();
+const { path: profileFile, source: profileSource, declaredName } = resolveProfile();
+/**
+ * The profile file currently in effect. Mutable because `switch_profile` swaps
+ * identity at runtime — `whoami` must report the live one, not the boot-time one.
+ * null = no profile is backing this session (anonymous, or token-only).
+ */
+let activeProfileFile: string | null = profileFile;
+/** No identity at all: serve tools/list, register nothing, connect nothing. */
+let anonymousMode = false;
 let profile: any = {};
 
 const DEFAULT_SERVER = "https://agents-chat.com";
@@ -159,14 +173,82 @@ const WS_URL = process.env.AGENTCHAT_URL || (() => {
 })();
 const REST_URL = serverUrl;
 
-if (existsSync(profileFile)) {
+// Identity, declared (not just hoisted) BEFORE anything can call apiFetch. These are
+// filled in from `profile` once the identity block below has run. Registration runs
+// before that and must not read them through the temporal dead zone — see below.
+let AGENT_ID = "";
+let TOKEN = "";
+let CAPABILITIES: string[] = [];
+
+// Native fetch, captured before the file-wide call-site rename to apiFetch so the
+// wrapper below can't recurse into itself.
+const nativeFetch = fetch;
+// All AgentsChat REST goes through apiFetch so every call gets, from one place:
+// (1) a timeout — a hung hub call must never block a tool forever; and
+// (2) the bearer token, injected only when absent and TOKEN is set (so the few
+//     conditional-auth sites keep their exact semantics). init is otherwise passed
+//     through untouched, so callers keep using r.ok / r.text() / r.json().
+//
+// This must be defined ABOVE the registration block. apiFetch is a hoisted function,
+// but its `timeoutMs = REST_TIMEOUT_MS` default and its `TOKEN` read are evaluated at
+// CALL time: when the bare-fetch→apiFetch refactor moved these call sites above the
+// const declarations, every /api/account/register call threw a TDZ ReferenceError that
+// the surrounding `catch` reported as "Server unreachable" — silently disabling
+// registration (and its dev-token migration twin, whose catch is empty). Registration
+// happens before TOKEN is assigned, so TOKEN is "" there and no Authorization header is
+// sent — exactly what the register endpoint expects.
+const REST_TIMEOUT_MS = 15_000;
+async function apiFetch(
+  input: string | URL,
+  init: RequestInit = {},
+  timeoutMs = REST_TIMEOUT_MS,
+): Promise<Response> {
+  const headers: Record<string, string> = { ...(init.headers as Record<string, string> | undefined) };
+  if (TOKEN && !("Authorization" in headers)) headers["Authorization"] = `Bearer ${TOKEN}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await nativeFetch(input as any, { ...init, headers, signal: init.signal ?? controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const hasToken = !!(cliArgs.token || process.env.AGENTCHAT_TOKEN);
+const identity = decideIdentity({
+  profileExists: existsSync(profileFile),
+  source: profileSource,
+  profileFile,
+  cliName: cliArgs.name,
+  declaredName,
+  registerFlag: !!cliArgs.register,
+  hasToken,
+  fallbackName: `Claude-${randomUUID().slice(0, 6)}`,
+});
+
+if (identity.mode === "profile") {
   profile = JSON.parse(readFileSync(profileFile, "utf-8"));
   process.stderr.write(`[agentchat] Profile loaded: ${profileFile}\n`);
+} else if (identity.mode === "env-creds") {
+  // Token handed to us directly — authenticate with it, register nothing, write nothing.
+  activeProfileFile = null;
+  process.stderr.write(`[agentchat] Using credentials from environment — not registering.\n`);
+} else if (identity.mode === "error") {
+  // A declared identity with no profile behind it. Inventing one is what corrupted
+  // attribution before, so fail loudly instead. Introspection never lands here.
+  process.stderr.write(`[agentchat] ERROR: ${identity.message}\n`);
+  process.exit(1);
+} else if (identity.mode === "anonymous") {
+  // Nothing declared. Stay alive so stdio introspection (initialize/tools/list) works,
+  // but create no account and persist no credentials.
+  anonymousMode = true;
+  activeProfileFile = null;
+  process.stderr.write(`[agentchat] ${identity.reason}\n`);
 } else {
-  // First run: auto-register with server to get a real agent key
-  const displayName = cliArgs.name || `Claude-${randomUUID().slice(0, 6)}`;
+  // Explicit opt-in: register a real account and persist it.
+  const displayName = identity.displayName;
   const caps = ["claude-code", "coding", "chat"];
-  process.stderr.write(`[agentchat] First run — registering with server...\n`);
+  process.stderr.write(`[agentchat] Registering "${displayName}" with server...\n`);
   try {
     const regRes = await apiFetch(`${REST_URL}/api/account/register`, {
       method: "POST",
@@ -190,7 +272,11 @@ if (existsSync(profileFile)) {
       profile = { agent_id: randomUUID(), display_name: displayName, token: "dev-token", capabilities: caps };
     }
   } catch (e) {
-    process.stderr.write(`[agentchat] Server unreachable, using local profile\n`);
+    // Always print the cause. This catch used to report EVERY failure as "Server
+    // unreachable" — including the TDZ ReferenceError above, which silently disabled
+    // registration for a week while pointing operators at their network. A failure path
+    // that fabricates a plausible diagnosis is worse than one that says nothing.
+    process.stderr.write(`[agentchat] Registration failed: ${e} — using local profile\n`);
     profile = { agent_id: randomUUID(), display_name: displayName, token: "dev-token", capabilities: caps };
   }
   mkdirSync(dirname(profileFile), { recursive: true });
@@ -198,8 +284,15 @@ if (existsSync(profileFile)) {
   process.stderr.write(`[agentchat] Profile saved: ${profileFile}\n`);
 }
 
-// Migrate old profiles with dev-token: auto-register to get real key
-if (profile.token === "dev-token") {
+// Second auto-register trigger: a loaded profile still carrying the `dev-token`
+// placeholder. Healing it is intended for a declared identity, but on the bare
+// shared default path it mints an anonymous account just like the first trigger.
+if (profile.token === "dev-token" && !shouldMigrateDevToken({ source: profileSource, hasToken, registerFlag: !!cliArgs.register })) {
+  process.stderr.write(
+    `[agentchat] Profile at ${profileFile} carries a dev-token but no identity was declared — ` +
+      `refusing to auto-register. Pass --name <name> or --register to create a real agent.\n`,
+  );
+} else if (profile.token === "dev-token") {
   process.stderr.write(`[agentchat] Migrating dev-token profile — registering with server...\n`);
   try {
     const regRes = await apiFetch(`${REST_URL}/api/account/register`, {
@@ -228,38 +321,17 @@ if (profile.token === "dev-token") {
         process.stderr.write(`[agentchat] Migrated with new ID: ${data.id}\n`);
       }
     }
-  } catch {}
-}
-
-let AGENT_ID = cliArgs.id || process.env.AGENTCHAT_AGENT_ID || profile.agent_id || randomUUID();
-let TOKEN = cliArgs.token || process.env.AGENTCHAT_TOKEN || profile.token || "dev-token";
-let CAPABILITIES: string[] = cliArgs.caps?.split(",") || profile.capabilities || ["claude-code", "coding", "chat"];
-
-// Native fetch, captured before the file-wide call-site rename to apiFetch so the
-// wrapper below can't recurse into itself.
-const nativeFetch = fetch;
-// All AgentsChat REST goes through apiFetch so every call gets, from one place:
-// (1) a timeout — a hung hub call must never block a tool forever; and
-// (2) the bearer token, injected only when absent and TOKEN is set (so the few
-//     conditional-auth sites keep their exact semantics). init is otherwise passed
-//     through untouched, so callers keep using r.ok / r.text() / r.json().
-const REST_TIMEOUT_MS = 15_000;
-async function apiFetch(
-  input: string | URL,
-  init: RequestInit = {},
-  timeoutMs = REST_TIMEOUT_MS,
-): Promise<Response> {
-  const headers: Record<string, string> = { ...(init.headers as Record<string, string> | undefined) };
-  if (TOKEN && !("Authorization" in headers)) headers["Authorization"] = `Bearer ${TOKEN}`;
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    return await nativeFetch(input as any, { ...init, headers, signal: init.signal ?? controller.signal });
-  } finally {
-    clearTimeout(timer);
+  } catch (e) {
+    // Was `catch {}`: it swallowed the same TDZ ReferenceError with no output at all.
+    process.stderr.write(`[agentchat] dev-token migration failed: ${e}\n`);
   }
 }
 
+// Now that the identity block has settled `profile`, bind the runtime identity.
+AGENT_ID = cliArgs.id || process.env.AGENTCHAT_AGENT_ID || profile.agent_id || randomUUID();
+TOKEN = cliArgs.token || process.env.AGENTCHAT_TOKEN || profile.token || "dev-token";
+CAPABILITIES = cliArgs.caps?.split(",") || profile.capabilities || ["claude-code", "coding", "chat"];
+
 // Update display name if provided via CLI
 if (cliArgs.name && profile.display_name !== cliArgs.name) {
   profile.display_name = cliArgs.name;
@@ -1610,13 +1682,14 @@ function mimeFromPath(p: string): string {
 }
 // Upload a local file via multipart POST /api/upload → { url, mime, size }.
 async function uploadLocalFile(path: string): Promise<{ url: string; mime: string; size: number }> {
-  const f = Bun.file(path);
-  if (!(await f.exists())) throw new Error(`file not found: ${path}`);
-  const mime = f.type && f.type !== "application/octet-stream" ? f.type : mimeFromPath(path);
-  const bytes = await f.arrayBuffer();
+  // node:fs (not Bun.file) so this runs on plain Node too — Bun supports node:fs
+  // identically, and the Node path is what registry introspection (Glama) uses.
+  if (!existsSync(path)) throw new Error(`file not found: ${path}`);
+  const mime = mimeFromPath(path);
+  const buf = readFileSync(path);
   const name = path.split("/").pop() || "upload";
   const form = new FormData();
-  form.append("file", new Blob([bytes], { type: mime }), name);
+  form.append("file", new Blob([new Uint8Array(buf)], { type: mime }), name);
   // No Content-Type header → fetch derives the multipart boundary itself.
   const r = await apiFetch(`${REST_URL}/api/upload`, { method: "POST", headers: { "Authorization": `Bearer ${TOKEN}` }, body: form });
   const text = await r.text();
@@ -1624,7 +1697,7 @@ async function uploadLocalFile(path: string): Promise<{ url: string; mime: strin
   let data: any;
   try { data = JSON.parse(text); } catch { throw new Error(`upload returned non-JSON: ${text.slice(0, 120)}`); }
   if (!data?.url) throw new Error(`upload response missing url: ${text.slice(0, 120)}`);
-  return { url: data.url as string, mime: (data.type as string) || mime, size: (data.size as number) ?? bytes.byteLength };
+  return { url: data.url as string, mime: (data.type as string) || mime, size: (data.size as number) ?? buf.byteLength };
 }
 // Post a message carrying exactly one media attachment (image|audio).
 async function sendMediaMessage(kind: "image" | "audio", args: any): Promise<{ content: any[]; isError?: boolean }> {
@@ -1981,15 +2054,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (!meta) return { content: [{ type: "text", text: `sync_skill: personal skill "${a.name}" not found (save it with save_skill — no chat_id).` }], isError: true };
         const currentVersion = Number(meta.version ?? 0);
         let cachedVersion: number | null = null;
-        try { cachedVersion = Number(JSON.parse(await Bun.file(pMeta).text()).version); } catch {}
+        try { cachedVersion = Number(JSON.parse(readFileSync(pMeta, "utf8")).version); } catch {}
         if (cachedVersion !== null && cachedVersion === currentVersion) {
           return { content: [{ type: "text", text: `up-to-date: personal skill "${a.name}" v${currentVersion} already at ${pMd} — no download. Read that file to run it.` }] };
         }
         const bodyR = await apiFetch(`${REST_URL}/api/skills/${encodeURIComponent(a.name)}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
         if (!bodyR.ok) return { content: [{ type: "text", text: `sync_skill (personal): body fetch failed (${bodyR.status})` }], isError: true };
         const doc = JSON.parse(await bodyR.text());
-        await Bun.write(pMd, String(doc?.body_markdown ?? ""));
-        await Bun.write(pMeta, JSON.stringify({ version: currentVersion, name: a.name, syncedAt: new Date().toISOString() }));
+        // node:fs (not Bun.write) — runs on plain Node too. Bun.write auto-creates
+        // parent dirs; writeFileSync does not, so mkdir the cache dir first.
+        mkdirSync(dirname(pMd), { recursive: true });
+        writeFileSync(pMd, String(doc?.body_markdown ?? ""));
+        writeFileSync(pMeta, JSON.stringify({ version: currentVersion, name: a.name, syncedAt: new Date().toISOString() }));
         return { content: [{ type: "text", text: `synced personal skill "${a.name}" v${currentVersion} → ${pMd} (was ${cachedVersion === null ? "missing" : `stale v${cachedVersion}`}). Read that file to run it.` }] };
       } catch (e: any) {
         return { content: [{ type: "text", text: `sync_skill (personal) error: ${String(e?.message || e).slice(0, 140)}` }], isError: true };
@@ -2013,7 +2089,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const currentVersion = Number(meta.version ?? 0);
       // 2. Local cache check — skip the body fetch if we already have this version.
       let cachedVersion: number | null = null;
-      try { cachedVersion = Number(JSON.parse(await Bun.file(metaPath).text()).version); } catch {}
+      try { cachedVersion = Number(JSON.parse(readFileSync(metaPath, "utf8")).version); } catch {}
       if (cachedVersion !== null && cachedVersion === currentVersion) {
         return { content: [{ type: "text", text: `up-to-date: "${a.doc_id}" v${currentVersion} already at ${mdPath} — no download. Read that file to run it.` }] };
       }
@@ -2022,9 +2098,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (!docR.ok) return { content: [{ type: "text", text: `sync_skill: fetch body failed (${docR.status})` }], isError: true };
       const doc = JSON.parse(await docR.text());
       const body = String(doc?.body_markdown ?? doc?.bodyMarkdown ?? "");
-      // 4. Write the local mirror + version sidecar.
-      await Bun.write(mdPath, body);
-      await Bun.write(metaPath, JSON.stringify({ version: currentVersion, title: doc?.title, doc_id: a.doc_id, chat_id: a.chat_id, syncedAt: new Date().toISOString() }));
+      // 4. Write the local mirror + version sidecar (node:fs, not Bun.write, for
+      // Node compat; mkdir the cache dir first since writeFileSync won't auto-create).
+      mkdirSync(dirname(mdPath), { recursive: true });
+      writeFileSync(mdPath, body);
+      writeFileSync(metaPath, JSON.stringify({ version: currentVersion, title: doc?.title, doc_id: a.doc_id, chat_id: a.chat_id, syncedAt: new Date().toISOString() }));
       const was = cachedVersion === null ? "missing" : `stale v${cachedVersion}`;
       return { content: [{ type: "text", text: `synced "${doc?.title || a.doc_id}" v${currentVersion} → ${mdPath} (was ${was}). Read that file to run it in your runtime.` }] };
     } catch (e: any) {
@@ -2710,7 +2788,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     } catch (e: any) {
       authLine = `REST auth: error (${String(e?.message || e).slice(0, 80)})`;
     }
-    return { content: [{ type: "text", text: `Profile: ${profile.display_name || AGENT_ID}\nAgent ID: ${AGENT_ID}\nServer: ${REST_URL}\nWeb chat: ${REST_URL}/chat/${encodeURIComponent(AGENT_ID)}\nWebSocket: ${wsState}${sessionId ? `\nSession: ${sessionId.slice(0, 12)}...` : ""}\n${healthLine}\n${authLine}\n${claimedLine}${claimHint ? `\n${claimHint}` : ""}\nCapabilities: ${CAPABILITIES.join(", ")}\nProfile file: ${profileFile}` }] };
+    return { content: [{ type: "text", text: `Profile: ${profile.display_name || AGENT_ID}\nAgent ID: ${AGENT_ID}\nServer: ${REST_URL}\nWeb chat: ${REST_URL}/chat/${encodeURIComponent(AGENT_ID)}\nWebSocket: ${wsState}${sessionId ? `\nSession: ${sessionId.slice(0, 12)}...` : ""}\n${healthLine}\n${authLine}\n${claimedLine}${claimHint ? `\n${claimHint}` : ""}\nCapabilities: ${CAPABILITIES.join(", ")}\nProfile file: ${activeProfileFile ?? (anonymousMode ? "(none — anonymous, no profile written)" : "(none — credentials from environment)")}` }] };
   }
 
   if (name === "list_channels") {
@@ -2903,11 +2981,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
     sessionId = null;
 
-    // Update identity
+    // 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;
@@ -3282,15 +3363,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 // Persisted to disk so reconnect/restart doesn't lose state
 const mentionTsFile = join(configDir, `mention-ts-${AGENT_ID}.json`);
 function loadMentionTimestamps(): Map<string, string> {
-  try {
-    const raw = readFileSync(mentionTsFile, "utf-8");
-    return new Map(Object.entries(JSON.parse(raw)));
-  } catch { return new Map(); }
+  return loadCursor(mentionTsFile, safeStderrWrite);
 }
+// Re-attempted on the next mention, but a persistent failure (perms, full disk) would
+// retry just as silently forever — and the state is gone on restart. So it reports.
 function saveMentionTimestamps(m: Map<string, string>) {
-  try {
-    writeFileSync(mentionTsFile, JSON.stringify(Object.fromEntries(m)));
-  } catch {}
+  persistCursor(mentionTsFile, m, safeStderrWrite);
 }
 const lastMentionTimestamp = loadMentionTimestamps();
 
@@ -3311,36 +3389,29 @@ const lastMentionTimestamp = loadMentionTimestamps();
 // connect or reconnect; if we missed anything, we find it.
 const lastSeenMessageTsFile = join(configDir, `last-seen-msg-ts-${AGENT_ID}.json`);
 function loadLastSeenMessageTs(): Map<string, string> {
-  try {
-    const raw = readFileSync(lastSeenMessageTsFile, "utf-8");
-    return new Map(Object.entries(JSON.parse(raw)));
-  } catch { return new Map(); }
-}
-function saveLastSeenMessageTs(m: Map<string, string>) {
-  try {
-    writeFileSync(lastSeenMessageTsFile, JSON.stringify(Object.fromEntries(m)));
-  } catch {}
+  return loadCursor(lastSeenMessageTsFile, safeStderrWrite);
 }
 const lastSeenMessageTs = loadLastSeenMessageTs();
 const cursorFlushIntervalMs = Math.max(
   500,
   Number(process.env.AGENTSCHAT_MCP_CURSOR_FLUSH_MS || 5000),
 );
-let lastSeenMessageTsDirty = false;
+/** Dirty flag lives in an object so flushCursor can clear it only on a landed write. */
+const cursorState = { dirty: false };
 let lastSeenMessageTsTimer: ReturnType<typeof setTimeout> | null = null;
 
 function flushLastSeenMessageTs() {
-  if (!lastSeenMessageTsDirty) return;
-  lastSeenMessageTsDirty = false;
+  if (!cursorState.dirty) return;
   if (lastSeenMessageTsTimer) {
     clearTimeout(lastSeenMessageTsTimer);
     lastSeenMessageTsTimer = null;
   }
-  saveLastSeenMessageTs(lastSeenMessageTs);
+  // Stays dirty if the write fails, so the shutdown fallback flush actually retries.
+  flushCursor(cursorState, () => persistCursor(lastSeenMessageTsFile, lastSeenMessageTs, safeStderrWrite));
 }
 
 function scheduleLastSeenMessageTsSave() {
-  lastSeenMessageTsDirty = true;
+  cursorState.dirty = true;
   if (lastSeenMessageTsTimer) return;
   lastSeenMessageTsTimer = setTimeout(() => {
     lastSeenMessageTsTimer = null;
@@ -3930,7 +4001,8 @@ function shutdownFromStdio(reason: string) {
   if (shuttingDown) return;
   shuttingDown = true;
   safeStderrWrite(`[agentchat] Stdio closed (${reason}), shutting down\n`);
-  try { flushLastSeenMessageTs(); } catch {}
+  // Persisting the read cursor is a state change, not teardown: report, never swallow.
+  try { flushLastSeenMessageTs(); } catch (e) { safeStderrWrite(`[agentchat] WARNING: read-cursor flush failed on shutdown: ${e}\n`); }
   try { heartbeat.stop(); } catch {}
   try { stopAllTypingHeartbeats(); } catch {}
   if (reconnectTimer) {
@@ -3967,7 +4039,7 @@ function installStdioLifecycleGuards() {
   process.stderr.on("error", handleOutputError);
   process.on("SIGPIPE", () => shutdownFromStdio("SIGPIPE"));
   process.on("beforeExit", () => {
-    try { flushLastSeenMessageTs(); } catch {}
+    try { flushLastSeenMessageTs(); } catch (e) { safeStderrWrite(`[agentchat] WARNING: read-cursor fallback flush failed: ${e}\n`); }
   });
 }
 
@@ -4000,7 +4072,13 @@ async function checkVersionStaleness(): Promise<void> {
 // --- Start ---
 async function main() {
   installStdioLifecycleGuards();
-  connectWS();
+  // Anonymous = no credentials to present. Connecting would just fail auth in a
+  // reconnect loop; stdio (initialize/tools/list) is served either way.
+  if (anonymousMode) {
+    process.stderr.write(`[agentchat] Anonymous — not connecting to the hub.\n`);
+  } else {
+    connectWS();
+  }
 
   // Stdio is the only supported transport. The --port HTTP SSE path was
   // removed in v0.6.7 — OpenClaw users should install the native channel