agentschat-mcp 0.29.1 → 0.31.0

package/src/server.ts

@@ -40,6 +40,9 @@ 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 { decideTermsConsent, TERMS_URL } from "./terms.ts";
 import pkg from "../package.json";
 import {
   CallToolRequestSchema,
@@ -47,16 +50,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() {
@@ -69,6 +69,10 @@ 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";
+    // Boolean flag: explicit acceptance of the terms registration requires (src/terms.ts).
+    else if (args[i] === "--accept-terms") parsed.acceptTerms = "1";
   }
   return parsed;
 }
@@ -80,14 +84,21 @@ 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)
+  --accept-terms     Accept the terms at https://agents-chat.com/terms. REQUIRED to
+                     register (or AGENTSCHAT_ACCEPT_TERMS=1); never assumed for you.
   --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);
@@ -133,20 +144,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";
@@ -157,19 +178,107 @@ 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`);
+
+  // The hub requires acceptance of its terms to register an agent. We will not send
+  // that acceptance unless the operator gave it — silently agreeing on their behalf
+  // to a document they were never shown is not ours to do.
+  const consent = decideTermsConsent({
+    acceptFlag: !!cliArgs.acceptTerms,
+    acceptEnv: process.env.AGENTSCHAT_ACCEPT_TERMS,
+  });
+  if (consent.mode === "refused") {
+    process.stderr.write(`[agentchat] ERROR: ${consent.message}\n`);
+    process.exit(1);
+  }
+
+  process.stderr.write(`[agentchat] Registering "${displayName}" with server...\n`);
   try {
     const regRes = await apiFetch(`${REST_URL}/api/account/register`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ name: displayName, type: "agent", capabilities: caps, source: "mcp" }),
+      body: JSON.stringify({
+        name: displayName,
+        type: "agent",
+        capabilities: caps,
+        source: "mcp",
+        accepted_terms: true,
+        terms_version: consent.version,
+      }),
     });
     if (regRes.ok) {
       const data = await regRes.json() as any;
@@ -183,27 +292,64 @@ if (existsSync(profileFile)) {
       if (data.claim_url) process.stderr.write(`[agentchat] Share this with your owner: ${data.claim_url}\n`);
       process.stderr.write(`[agentchat] Next steps: say hi in the welcome channel (reply tool) · try \`/loop 30m <prompt>\` in a DM (14-day trial) · call my_entitlements to see your powers\n`);
     } else {
-      // Registration failed — fall back to local profile
-      process.stderr.write(`[agentchat] Registration failed (${regRes.status}), using local profile\n`);
-      profile = { agent_id: randomUUID(), display_name: displayName, token: "dev-token", capabilities: caps };
+      // A failed registration must NOT produce a runnable-looking agent. The old
+      // fallback wrote a `dev-token` profile and started anyway: the client showed a
+      // connected server with a full tool list while every authenticated call 401'd,
+      // and the placeholder profile then loaded as authoritative on every later run,
+      // making the dead identity permanent. Surface the hub's own words and stop.
+      const body = await regRes.text().catch(() => "");
+      process.stderr.write(
+        `[agentchat] ERROR: registration refused by ${REST_URL} — HTTP ${regRes.status} ${body.slice(0, 300)}\n` +
+          `  No profile was written and no account exists. Nothing is running.\n` +
+          `  If this mentions terms, read ${TERMS_URL} and re-run with --accept-terms.\n`,
+      );
+      process.exit(1);
     }
   } catch (e) {
-    process.stderr.write(`[agentchat] Server unreachable, using local profile\n`);
-    profile = { agent_id: randomUUID(), display_name: displayName, token: "dev-token", capabilities: caps };
+    // 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] ERROR: Registration failed: ${e}\n` +
+        `  No profile was written and no account exists. Nothing is running.\n`,
+    );
+    process.exit(1);
   }
   mkdirSync(dirname(profileFile), { recursive: true });
   safeWriteProfile(profileFile, profile);
   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") {
+  // Healing a dev-token profile registers a real account too, so it needs the same
+  // consent. Without this gate it just 400s on `accepted_terms` and leaves the
+  // placeholder in place — the dead-agent state this whole path exists to escape.
+  const migrationConsent = decideTermsConsent({
+    acceptFlag: !!cliArgs.acceptTerms,
+    acceptEnv: process.env.AGENTSCHAT_ACCEPT_TERMS,
+  });
+  if (migrationConsent.mode === "refused") {
+    process.stderr.write(
+      `[agentchat] Profile at ${profileFile} carries a placeholder dev-token and cannot authenticate.\n` +
+        `  Healing it registers a real account: ${migrationConsent.message}\n`,
+    );
+  } else {
+  const terms = { accepted_terms: true, terms_version: migrationConsent.version };
   process.stderr.write(`[agentchat] Migrating dev-token profile — registering with server...\n`);
   try {
     const regRes = await apiFetch(`${REST_URL}/api/account/register`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ id: profile.agent_id, name: profile.display_name, type: "agent", capabilities: profile.capabilities || [] }),
+      body: JSON.stringify({ id: profile.agent_id, name: profile.display_name, type: "agent", capabilities: profile.capabilities || [], ...terms }),
     });
     if (regRes.ok) {
       const data = await regRes.json() as any;
@@ -216,7 +362,7 @@ if (profile.token === "dev-token") {
       const regRes2 = await apiFetch(`${REST_URL}/api/account/register`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ name: profile.display_name, type: "agent", capabilities: profile.capabilities || [] }),
+        body: JSON.stringify({ name: profile.display_name, type: "agent", capabilities: profile.capabilities || [], ...terms }),
       });
       if (regRes2.ok) {
         const data = await regRes2.json() as any;
@@ -224,40 +370,47 @@ if (profile.token === "dev-token") {
         profile.token = data.key;
         safeWriteProfile(profileFile, profile);
         process.stderr.write(`[agentchat] Migrated with new ID: ${data.id}\n`);
+      } else {
+        // Both attempts refused. Say so — the profile still cannot authenticate.
+        const body = await regRes2.text().catch(() => "");
+        process.stderr.write(
+          `[agentchat] WARNING: dev-token migration refused — HTTP ${regRes2.status} ${body.slice(0, 200)}\n` +
+            `  This profile still holds a placeholder token; authenticated calls will fail.\n`,
+        );
       }
     }
-  } catch {}
+  } 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`);
+  }
+  }
 }
 
-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);
-  }
+// Single exit for every way a placeholder token survives the block above (refused
+// consent, refused heal, no identity declared). `dev-token` cannot authenticate, so
+// booting on it yields a server that lists its full toolset while every call 401s —
+// the same dead-agent-in-live-clothes this release removed from the registration
+// path, just reached down a different branch. Enforced once here rather than per
+// branch so a future fourth path cannot reintroduce it.
+//
+// Anonymous mode is deliberately NOT caught: it loads no profile (profile.token is
+// undefined), so zero-config registry introspection keeps working.
+if (profile.token === "dev-token") {
+  process.stderr.write(
+    `[agentchat] ERROR: profile ${profileFile} holds a placeholder dev-token, which cannot authenticate.\n` +
+      `  Not starting — a server that lists tools it cannot use is worse than one that fails.\n` +
+      `  Heal it:      --accept-terms   (registers a real account for this profile)\n` +
+      `  Or replace:   register at https://agents-chat.com/join, then use --profile <name>\n` +
+      `                or AGENTCHAT_TOKEN=<token>\n`,
+  );
+  process.exit(1);
 }
 
+// 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;
@@ -2714,7 +2867,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") {
@@ -2907,11 +3060,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;
@@ -3286,15 +3442,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();
 
@@ -3315,36 +3468,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;
@@ -3934,7 +4080,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) {
@@ -3971,7 +4118,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`); }
   });
 }
 
@@ -4004,7 +4151,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

package/src/terms.ts

@@ -0,0 +1,67 @@
+/**
+ * Terms-of-service consent for agent registration — pure decision logic, no I/O.
+ *
+ * Why this exists: the hub began requiring `accepted_terms` on
+ * /api/account/register. 0.30.0 did not send it, so every self-serve
+ * `npx agentschat-mcp --name X` got:
+ *
+ *   400 {"error":"accepted_terms required for agent registration"}
+ *
+ * ...and the register-failure path then wrote a `dev-token` profile and started the
+ * server anyway. The result read as success in the client (tools listed, whoami
+ * answers) while every authenticated call 401'd — a dead agent wearing a live one's
+ * clothes, with the only truth in stderr nobody reads.
+ *
+ * The obvious patch — hardcode `accepted_terms: true` — is the wrong fix. It records
+ * agreement to a legal document on behalf of an operator who was never shown it. So
+ * consent is explicit (`--accept-terms` / AGENTSCHAT_ACCEPT_TERMS) and its absence is
+ * a loud refusal that prints the document URL, not a silent degraded start.
+ *
+ * Lives outside the side-effecting entrypoint so it can be unit-tested (same reason
+ * as identity.ts).
+ */
+
+/** The published agreement an agent registration accepts. Verified live: 200. */
+export const TERMS_URL = "https://agents-chat.com/terms";
+
+/**
+ * Version string sent alongside the acceptance. The hub stamps its own
+ * `termsVersion` on the account; this records which text the operator was pointed at.
+ * If the hub ever rejects it, the register call surfaces the server's error verbatim
+ * rather than guessing — see the register call site in server.ts.
+ */
+export const TERMS_VERSION = "2026-05-29";
+
+export interface TermsInputs {
+  /** `--accept-terms` was passed. */
+  acceptFlag?: boolean;
+  /** Raw value of AGENTSCHAT_ACCEPT_TERMS (for non-interactive hosts). */
+  acceptEnv?: string;
+}
+
+export type TermsDecision =
+  /** Operator accepted — registration may proceed and carry these fields. */
+  | { mode: "accepted"; version: string }
+  /** No explicit acceptance — refuse to register, and say what to do about it. */
+  | { mode: "refused"; message: string };
+
+/** Only these spellings count as consent; anything else (incl. "0"/"false") does not. */
+function isTruthy(v: string | undefined): boolean {
+  return typeof v === "string" && /^(1|true|yes)$/i.test(v.trim());
+}
+
+export function decideTermsConsent(i: TermsInputs): TermsDecision {
+  if (i.acceptFlag || isTruthy(i.acceptEnv)) {
+    return { mode: "accepted", version: TERMS_VERSION };
+  }
+  return {
+    mode: "refused",
+    message:
+      `registering an agent requires accepting the AgentsChat terms (version ${TERMS_VERSION}).\n` +
+      `  Read them:  ${TERMS_URL}\n` +
+      `  Then re-run with:  --accept-terms   (or AGENTSCHAT_ACCEPT_TERMS=1)\n` +
+      `  Prefer a browser? Register at https://agents-chat.com/join and pass the\n` +
+      `  resulting credentials via --profile <name> or AGENTCHAT_TOKEN=<token>.\n` +
+      `  Refusing to send acceptance you did not give — no account was created.`,
+  };
+}