agentschat-mcp 0.23.1 → 0.24.0

package/src/server.ts

@@ -4,6 +4,17 @@
  * 像 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);
+}
+
 // ── Proxy bypass ──────────────────────────────────────────────────
 // MCP subprocess inherits the parent's HTTP_PROXY/HTTPS_PROXY which
 // are set for Claude API access. But this plugin only talks to
@@ -25,6 +36,12 @@ if (process.env.AGENTCHAT_NO_PROXY === "1") {
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { redactSecrets } from "./redact.ts";
+import { matchesMention } from "./mentions.ts";
+import { messageDedupKey, MessageDedup } from "./dedup.ts";
+import { computeReconnectDelay } from "./reconnect.ts";
+import { normalizeTimestampForCursor } from "./timestamps.ts";
+import { validateToolArgs } from "./argcheck.ts";
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
@@ -150,7 +167,7 @@ if (existsSync(profileFile)) {
   const caps = ["claude-code", "coding", "chat"];
   process.stderr.write(`[agentchat] First run — registering with server...\n`);
   try {
-    const regRes = await fetch(`${REST_URL}/api/account/register`, {
+    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" }),
@@ -184,7 +201,7 @@ if (existsSync(profileFile)) {
 if (profile.token === "dev-token") {
   process.stderr.write(`[agentchat] Migrating dev-token profile — registering with server...\n`);
   try {
-    const regRes = await fetch(`${REST_URL}/api/account/register`, {
+    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 || [] }),
@@ -197,7 +214,7 @@ if (profile.token === "dev-token") {
       process.stderr.write(`[agentchat] Migrated! New key saved. ID: ${data.id}\n`);
     } else {
       // ID conflict (409) — old UUID taken. Register with auto-generated id instead.
-      const regRes2 = await fetch(`${REST_URL}/api/account/register`, {
+      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 || [] }),
@@ -217,6 +234,31 @@ let AGENT_ID = cliArgs.id || process.env.AGENTCHAT_AGENT_ID || profile.agent_id
 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);
+  }
+}
+
 // Update display name if provided via CLI
 if (cliArgs.name && profile.display_name !== cliArgs.name) {
   profile.display_name = cliArgs.name;
@@ -228,7 +270,7 @@ if (profile.token && profile.token !== "dev-token") {
     // /api/account/:id now requires auth (server tick 88 info-leak
     // fix). Without the Bearer header the welcome/claim banner
     // silently skipped on every MCP startup.
-    const acctRes = await fetch(`${REST_URL}/api/account/${encodeURIComponent(AGENT_ID)}`, {
+    const acctRes = await apiFetch(`${REST_URL}/api/account/${encodeURIComponent(AGENT_ID)}`, {
       headers: { "Authorization": `Bearer ${profile.token}` },
     });
     if (acctRes.ok) {
@@ -256,6 +298,47 @@ try {
 } catch {}
 
 let ws: WebSocket | null = null;
+
+// ── Agent "thinking" typing heartbeat ────────────────────────────────────────
+// While we process an inbound DM/@mention, pulse a cross-pod ephemeral typing
+// frame (~2s) so a human on ANY pod sees the agent think for the whole duration.
+// cross_pod:true → the hub fans out via publishToRemoteInstances; typing frames
+// are never persisted (deliverLocalOnly), so this is zero-write. Rate 2s ≪ the
+// per-agent 30/10s WS inbound cap. Stops when we reply to the channel, at a
+// safety cap, or on shutdown — all timers tracked, so no leak. Survives a brief
+// reconnect (frames no-op while the socket is down, resume on the new socket).
+const TYPING_HEARTBEAT_MS = 2_000;
+const TYPING_HEARTBEAT_MAX_MS = 120_000;
+const typingHeartbeats = new Map<string, { interval: ReturnType<typeof setInterval>; cap: ReturnType<typeof setTimeout> }>();
+function sendTypingFrame(channelId: string) {
+  if (ws && ws.readyState === WebSocket.OPEN) {
+    try {
+      ws.send(JSON.stringify({ type: "typing", channel_id: channelId, sender_id: AGENT_ID, cross_pod: true }));
+    } catch {}
+  }
+}
+function startTypingHeartbeat(channelId: string) {
+  if (!channelId) return;
+  stopTypingHeartbeat(channelId); // reset if one is already running for this channel
+  sendTypingFrame(channelId); // immediate first pulse
+  const interval = setInterval(() => sendTypingFrame(channelId), TYPING_HEARTBEAT_MS);
+  const cap = setTimeout(() => stopTypingHeartbeat(channelId), TYPING_HEARTBEAT_MAX_MS);
+  typingHeartbeats.set(channelId, { interval, cap });
+}
+function stopTypingHeartbeat(channelId: string) {
+  const h = typingHeartbeats.get(channelId);
+  if (!h) return;
+  clearInterval(h.interval);
+  clearTimeout(h.cap);
+  typingHeartbeats.delete(channelId);
+}
+function stopAllTypingHeartbeats() {
+  for (const h of typingHeartbeats.values()) {
+    clearInterval(h.interval);
+    clearTimeout(h.cap);
+  }
+  typingHeartbeats.clear();
+}
 let sessionId: string | null = null;
 let shuttingDown = false;
 let transport: StdioServerTransport | null = null;
@@ -518,8 +601,7 @@ For non-trivial AgentsChat work, start from Workspace Graph/OKR state, preserve
 
 // --- Tools ---
 
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-  tools: filterVisibleTools([
+const ALL_TOOL_DEFS = [
     {
       name: "reply",
       description: "Reply to an AgentsChat message. Pass the chat_id (channel_id) from the channel tag.",
@@ -1019,6 +1101,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: "Per-caller perspective on the tree. mine-active = my active tasks. blocking-me = tasks I'm waiting on. blocked-by-me = tasks waiting on me. related = anchor task's neighbourhood (requires task_id). Empty objectives are pruned.",
           },
           task_id: { type: "string", description: "Anchor task id; only meaningful with view=related" },
+          shape: { type: "string", enum: ["summary"], description: "shape=summary returns a compact scan view (KR one-liners + task rollups, only doing/blocked expanded) — far fewer tokens. Drill into one objective with objective_id for the full subtree." },
+          objective_id: { type: "string", description: "Return the full subtree (KRs + tasks + comments) for a single objective." },
         },
       },
     },
@@ -1264,15 +1348,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["chat_id", "doc_id"],
       },
     },
-  ]),
-}));
-
-/** Redact sensitive tokens from outgoing message content */
-function redactSecrets(text: string): string {
-  return text
-    .replace(/ac_[A-Za-z0-9]{16,}/g, "ac_***REDACTED***")
-    .replace(/eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, "***JWT_REDACTED***");
-}
+];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: filterVisibleTools(ALL_TOOL_DEFS) }));
+// Runtime input-validation registry: tool name → its declared inputSchema.
+// Consulted at dispatch to reject contract-violating args with a clear isError (B1b).
+const TOOL_INPUT_SCHEMAS: Map<string, any> = new Map(
+  (ALL_TOOL_DEFS as any[]).map((t) => [t.name, t.inputSchema]),
+);
+
+// redactSecrets now lives in ./redact.ts (imported above) so it can be
+// unit-tested without loading this side-effecting entrypoint.
 
 /**
  * Per-channel member cache for the bare-@-to-paren resolver below.
@@ -1287,7 +1372,7 @@ async function fetchChannelMembers(chatId: string): Promise<{ agent_id: string;
   const hit = memberCache.get(chatId);
   if (hit && now - hit.at < MEMBER_CACHE_TTL_MS) return hit.members;
   try {
-    const r = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(chatId)}/members`, {
+    const r = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(chatId)}/members`, {
       headers: { "Authorization": `Bearer ${TOKEN}` },
     });
     if (!r.ok) return hit?.members || [];
@@ -1329,9 +1414,43 @@ async function resolveBareMentions(chatId: string, text: string): Promise<string
   });
 }
 
+// ── Tool handler registry (strangler-fig migration off the if-chain) ──────────
+// Handlers registered here are dispatched O(1) in the CallTool handler below,
+// after the arg-validation + extended-compat + visibility preamble; any tool not
+// yet migrated falls through to the legacy if-chain. Handlers close over module
+// state (ws, TOKEN, apiFetch, AGENT_ID, …) exactly as the inline blocks did, and
+// are populated at module load. Migrating in verified slices, not a big-bang.
+type ToolHandler = (args: any, name: string, request: any) => Promise<{ content: any[]; isError?: boolean }>;
+const HANDLERS = new Map<string, ToolHandler>();
+
+HANDLERS.set("send_typing", async (args) => {
+  const { chat_id } = args as { chat_id: string };
+  if (ws && ws.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify({
+      type: "typing",
+      channel_id: chat_id,
+      sender_id: AGENT_ID,
+      cross_pod: true, // agent-originated → hub fans out cross-pod (humans on other pods see it)
+    }));
+  }
+  return { content: [{ type: "text", text: "Typing indicator dispatched" }] };
+});
+
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   let { name, arguments: args } = request.params;
   let viaExtendedCompat = false;
+  // Central failure boundary: any handler that throws (network, JSON, ws.send,
+  // unexpected shape) becomes an isError result instead of a silent/opaque
+  // SDK error, so the calling agent always learns the call failed. Explicit
+  // error returns below carry isError:true individually.
+  try {
+    // Validate args against the tool's declared inputSchema (required present +
+    // declared types) before any side effect. Permissive: unknown tools and
+    // undeclared fields pass through; only contract violations are rejected.
+    if (TOOL_INPUT_SCHEMAS.has(name)) {
+      const argErr = validateToolArgs(TOOL_INPUT_SCHEMAS.get(name), args);
+      if (argErr) return { content: [{ type: "text", text: `${name}: ${argErr}` }], isError: true };
+    }
 
   if (name === "list_skills") {
     const { chat_id } = (args || {}) as { chat_id?: string };
@@ -1345,7 +1464,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     };
     if (chat_id) {
       try {
-        const r = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/docs`, {
+        const r = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/docs`, {
           headers: { "Authorization": `Bearer ${TOKEN}` },
         });
         if (r.ok) out.channel_skills = extractChannelDocsPayload(JSON.parse(await r.text())).filter(isSkillDoc).map(compactSkillDoc);
@@ -1356,10 +1475,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
     // Personal skills (per-owner, follow you across agents). sync_skill(name=…) / load via GET /api/skills/:name.
     try {
-      const pr = await fetch(`${REST_URL}/api/skills`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      const pr = await apiFetch(`${REST_URL}/api/skills`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
       if (pr.ok) out.personal_skills = (JSON.parse(await pr.text()).skills) || [];
     } catch { /* best-effort */ }
-    return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
+    return { content: [{ type: "text", text: JSON.stringify(out) }] };
   }
 
   if (name === "load_skill") {
@@ -1367,12 +1486,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // CHANNEL skill: chat_id + doc_id (full frontmatter/metadata handling).
     if (chat_id && doc_id) {
       try {
-        const r = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/docs/${encodeURIComponent(doc_id)}`, {
+        const r = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/docs/${encodeURIComponent(doc_id)}`, {
           headers: { "Authorization": `Bearer ${TOKEN}` },
         });
         const text = await r.text();
         if (!r.ok) {
-          return { content: [{ type: "text", text: `load_skill (channel) failed (${r.status}): ${text.slice(0, 200)}` }] };
+          return { content: [{ type: "text", text: `load_skill (channel) failed (${r.status}): ${text.slice(0, 200)}` }], isError: true };
         }
         const doc = JSON.parse(text);
         const body = doc?.body_markdown ?? doc?.bodyMarkdown ?? "";
@@ -1401,14 +1520,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }],
         };
       } catch (e: any) {
-        return { content: [{ type: "text", text: `load_skill (channel) network/parse error: ${String(e?.message || e).slice(0, 120)}` }] };
+        return { content: [{ type: "text", text: `load_skill (channel) network/parse error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
       }
     }
     // GLOBAL skill: skill_id (default workspace-driven-eng).
     const id = skill_id || DEFAULT_GLOBAL_SKILL_ID;
     const skill = GLOBAL_SKILLS[id];
     if (!skill) {
-      return { content: [{ type: "text", text: `Unknown global skill: ${id}` }] };
+      return { content: [{ type: "text", text: `Unknown global skill: ${id}` }], isError: true };
     }
     return { content: [{ type: "text", text: `${skill.body}\n\nLoaded as global skill "${id}".` }] };
   }
@@ -1416,20 +1535,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (name === "save_memory") {
     const a = (args || {}) as { name?: string; body?: string; description?: string };
     if (!a.name || !a.body) {
-      return { content: [{ type: "text", text: "save_memory needs name (slug) + body (markdown). Optional description (one-line index hook)." }] };
+      return { content: [{ type: "text", text: "save_memory needs name (slug) + body (markdown). Optional description (one-line index hook)." }], isError: true };
     }
     try {
-      const r = await fetch(`${REST_URL}/api/memory/${encodeURIComponent(a.name)}`, {
+      const r = await apiFetch(`${REST_URL}/api/memory/${encodeURIComponent(a.name)}`, {
         method: "PUT",
         headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
         body: JSON.stringify({ body_markdown: a.body, description: a.description }),
       });
       const text = await r.text();
-      if (!r.ok) return { content: [{ type: "text", text: `save_memory failed (${r.status}): ${text.slice(0, 240)}` }] };
+      if (!r.ok) return { content: [{ type: "text", text: `save_memory failed (${r.status}): ${text.slice(0, 240)}` }], isError: true };
       const resp = JSON.parse(text);
       return { content: [{ type: "text", text: `Saved memory "${resp.name}" (v${resp.version}, ${resp.bytes}B) under your agent_id. Restore later: load_memory (index) → load_memory("${resp.name}").` }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `save_memory network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `save_memory network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -1437,9 +1556,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const a = (args || {}) as { name?: string };
     try {
       const path = a.name ? `/api/memory/${encodeURIComponent(a.name)}` : `/api/memory`;
-      const r = await fetch(`${REST_URL}${path}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      const r = await apiFetch(`${REST_URL}${path}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
       const text = await r.text();
-      if (!r.ok) return { content: [{ type: "text", text: `load_memory failed (${r.status}): ${text.slice(0, 240)}` }] };
+      if (!r.ok) return { content: [{ type: "text", text: `load_memory failed (${r.status}): ${text.slice(0, 240)}` }], isError: true };
       const resp = JSON.parse(text);
       if (a.name) {
         return { content: [{ type: "text", text: `# memory: ${resp.name} (v${resp.version})\n\n${resp.body_markdown || ""}` }] };
@@ -1449,14 +1568,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const idx = items.map((m: any) => `- ${m.name}${m.description ? ` — ${m.description}` : ""}`).join("\n");
       return { content: [{ type: "text", text: `Your memory index (${items.length} docs). Load one in full with load_memory("<name>"):\n\n${idx}` }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `load_memory network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `load_memory network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
   if (name === "save_skill") {
     const a = (args || {}) as { chat_id?: string; name?: string; description?: string; body?: string; doc_id?: string; level?: number };
     if (!a.name || !a.description) {
-      return { content: [{ type: "text", text: "save_skill needs name + description (body is the skill markdown). Pass chat_id for a CHANNEL skill, or OMIT chat_id for a PERSONAL skill that follows you across all your agents." }] };
+      return { content: [{ type: "text", text: "save_skill needs name + description (body is the skill markdown). Pass chat_id for a CHANNEL skill, or OMIT chat_id for a PERSONAL skill that follows you across all your agents." }], isError: true };
     }
     // Skill markdown = YAML frontmatter (name, description) + body — the exact
     // shape parseSkillFrontmatter + the skill validators expect.
@@ -1466,17 +1585,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (!a.chat_id) {
       const pslug = String(a.doc_id || a.name).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[^a-z0-9]+/, "").replace(/[^a-z0-9]+$/, "").slice(0, 64) || "skill";
       try {
-        const r = await fetch(`${REST_URL}/api/skills/${encodeURIComponent(pslug)}`, {
+        const r = await apiFetch(`${REST_URL}/api/skills/${encodeURIComponent(pslug)}`, {
           method: "PUT",
           headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
           body: JSON.stringify({ body_markdown: md }),
         });
         const text = await r.text();
-        if (!r.ok) return { content: [{ type: "text", text: `save_skill (personal) failed (${r.status}): ${text.slice(0, 240)}` }] };
+        if (!r.ok) return { content: [{ type: "text", text: `save_skill (personal) failed (${r.status}): ${text.slice(0, 240)}` }], isError: true };
         const resp = JSON.parse(text);
         return { content: [{ type: "text", text: `Saved PERSONAL skill "${a.name}" as "${pslug}" (v${resp.version}) — shared across all your agents. Pull/refresh: sync_skill(name="${pslug}"); list: list_skills.` }] };
       } catch (e: any) {
-        return { content: [{ type: "text", text: `save_skill (personal) network error: ${String(e?.message || e).slice(0, 120)}` }] };
+        return { content: [{ type: "text", text: `save_skill (personal) network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
       }
     }
     // CHANNEL skill (chat_id given). Stable doc id: caller-supplied, else slug of name.
@@ -1487,24 +1606,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       // If-Match: fetch current version (0 = create). The doc store uses
       // optimistic concurrency; "0" creates, current version updates.
       let ifMatch = "0";
-      const cur = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(a.chat_id)}/docs/${encodeURIComponent(docId)}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      const cur = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(a.chat_id)}/docs/${encodeURIComponent(docId)}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
       if (cur.ok) {
         const curDoc = await cur.json().catch(() => null) as any;
         if (curDoc && curDoc.version != null) ifMatch = String(curDoc.version);
       }
-      const r = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(a.chat_id)}/docs/${encodeURIComponent(docId)}`, {
+      const r = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(a.chat_id)}/docs/${encodeURIComponent(docId)}`, {
         method: "PUT",
         headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json", "If-Match": ifMatch },
         body: JSON.stringify({ kind: "channel_skill", level, title: a.name, body_markdown: md }),
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `save_skill failed (${r.status}): ${text.slice(0, 240)}` }] };
+        return { content: [{ type: "text", text: `save_skill failed (${r.status}): ${text.slice(0, 240)}` }], isError: true };
       }
       const verb = ifMatch === "0" ? "Saved" : "Updated";
       return { content: [{ type: "text", text: `${verb} skill "${a.name}" → ${a.chat_id}/${docId} (L${level}). Others load it with: load_skill(chat_id="${a.chat_id}", doc_id="${docId}") — discoverable via list_skills(chat_id="${a.chat_id}").` }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `save_skill network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `save_skill network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -1519,29 +1638,29 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const pBase = `${cacheDir}/personal__${safe(a.name)}`;
       const pMd = `${pBase}.md`; const pMeta = `${pBase}.json`;
       try {
-        const listR = await fetch(`${REST_URL}/api/skills`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
-        if (!listR.ok) return { content: [{ type: "text", text: `sync_skill (personal): list failed (${listR.status})` }] };
+        const listR = await apiFetch(`${REST_URL}/api/skills`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+        if (!listR.ok) return { content: [{ type: "text", text: `sync_skill (personal): list failed (${listR.status})` }], isError: true };
         const meta = (JSON.parse(await listR.text()).skills || []).find((s: any) => s.name === a.name);
-        if (!meta) return { content: [{ type: "text", text: `sync_skill: personal skill "${a.name}" not found (save it with save_skill — no chat_id).` }] };
+        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 {}
         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 fetch(`${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})` }] };
+        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() }));
         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)}` }] };
+        return { content: [{ type: "text", text: `sync_skill (personal) error: ${String(e?.message || e).slice(0, 140)}` }], isError: true };
       }
     }
     // CHANNEL skill: chat_id + doc_id.
     if (!a.chat_id || !a.doc_id) {
-      return { content: [{ type: "text", text: "sync_skill needs (chat_id + doc_id) for a CHANNEL skill, or (name) for a PERSONAL skill." }] };
+      return { content: [{ type: "text", text: "sync_skill needs (chat_id + doc_id) for a CHANNEL skill, or (name) for a PERSONAL skill." }], isError: true };
     }
     const base = `${cacheDir}/${safe(a.chat_id)}__${safe(a.doc_id)}`;
     const mdPath = `${base}.md`;
@@ -1549,11 +1668,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
       // 1. Cheap version check: docs-list returns each doc's version WITHOUT the
       // body, so "is my local copy current?" costs one light call.
-      const listR = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(a.chat_id)}/docs`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
-      if (!listR.ok) return { content: [{ type: "text", text: `sync_skill: docs-list failed (${listR.status})` }] };
+      const listR = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(a.chat_id)}/docs`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      if (!listR.ok) return { content: [{ type: "text", text: `sync_skill: docs-list failed (${listR.status})` }], isError: true };
       const docs = extractChannelDocsPayload(JSON.parse(await listR.text()));
       const meta = docs.find((d: any) => (d?.id ?? d?.doc_id) === a.doc_id);
-      if (!meta) return { content: [{ type: "text", text: `sync_skill: skill "${a.doc_id}" not found in channel ${a.chat_id}` }] };
+      if (!meta) return { content: [{ type: "text", text: `sync_skill: skill "${a.doc_id}" not found in channel ${a.chat_id}` }], isError: true };
       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;
@@ -1562,8 +1681,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return { content: [{ type: "text", text: `up-to-date: "${a.doc_id}" v${currentVersion} already at ${mdPath} — no download. Read that file to run it.` }] };
       }
       // 3. Missing/stale → fetch the body (the only expensive call, on the cold path).
-      const docR = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(a.chat_id)}/docs/${encodeURIComponent(a.doc_id)}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
-      if (!docR.ok) return { content: [{ type: "text", text: `sync_skill: fetch body failed (${docR.status})` }] };
+      const docR = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(a.chat_id)}/docs/${encodeURIComponent(a.doc_id)}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      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.
@@ -1572,7 +1691,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       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) {
-      return { content: [{ type: "text", text: `sync_skill error: ${String(e?.message || e).slice(0, 140)}` }] };
+      return { content: [{ type: "text", text: `sync_skill error: ${String(e?.message || e).slice(0, 140)}` }], isError: true };
     }
   }
 
@@ -1598,7 +1717,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { group_name } = (args || {}) as { group_name: ToolGroupName };
     const group = TOOL_GROUPS.find((item) => item.name === group_name);
     if (!group) {
-      return { content: [{ type: "text", text: `Unknown tool group: ${String(group_name)}` }] };
+      return { content: [{ type: "text", text: `Unknown tool group: ${String(group_name)}` }], isError: true };
     }
     const wasLoaded = loadedToolGroups.has(group.name);
     if (!wasLoaded) {
@@ -1623,7 +1742,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { tool_name, arguments: forwardedArgs } = (args || {}) as { tool_name?: string; arguments?: Record<string, unknown> };
     const groupName = tool_name ? TOOL_NAME_TO_GROUP.get(tool_name) : undefined;
     if (!tool_name || !groupName) {
-      return { content: [{ type: "text", text: `invoke_extended_tool only supports known extended tools.` }] };
+      return { content: [{ type: "text", text: `invoke_extended_tool only supports known extended tools.` }], isError: true };
     }
     name = tool_name;
     args = forwardedArgs || {};
@@ -1643,8 +1762,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
   }
 
+  // Registry dispatch: a migrated handler is looked up O(1) here; any tool not
+  // yet migrated falls through to the legacy if-chain below (strangler-fig).
+  {
+    const registered = HANDLERS.get(name);
+    if (registered) return await registered(args, name, request);
+  }
+
   if (name === "reply") {
     const { chat_id, text: rawText } = args as { chat_id: string; text: string };
+    stopTypingHeartbeat(chat_id); // we're answering this channel → stop the "thinking" pulse
     // Order: resolve bare @<display_name> to paren form FIRST (so the
     // receiving MCP plugin's regex triggers), then redact secrets so
     // an accidental `ac_xxx` in the text gets masked regardless of
@@ -1652,7 +1779,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const text = redactSecrets(await resolveBareMentions(chat_id, rawText));
     // Use REST API for reliable delivery (WebSocket may be half-open after deploy)
     try {
-      const r = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/messages`, {
+      const r = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/messages`, {
         method: "POST",
         headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` },
         body: JSON.stringify({
@@ -1682,18 +1809,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
   }
 
-  if (name === "send_typing") {
-    const { chat_id } = args as { chat_id: string };
-    if (ws && ws.readyState === WebSocket.OPEN) {
-      ws.send(JSON.stringify({
-        type: "typing",
-        channel_id: chat_id,
-        sender_id: AGENT_ID,
-      }));
-    }
-    return { content: [{ type: "text", text: "Typing indicator dispatched" }] };
-  }
-
   if (name === "react") {
     const { chat_id, message_id, emoji, action } = args as any;
     if (ws && ws.readyState === WebSocket.OPEN) {
@@ -1734,8 +1849,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 
   if (name === "edit_message") {
-    const { chat_id, message_id, new_content } = args as any;
+    const { chat_id, message_id, new_content: rawNewContent } = args as any;
+    if (typeof rawNewContent !== "string") {
+      return { content: [{ type: "text", text: "Error: new_content (string) required" }] };
+    }
     if (ws && ws.readyState === WebSocket.OPEN) {
+      // Mirror reply(): resolve bare @mentions then redact secrets so an
+      // accidental ac_/JWT in edited content is masked like every other
+      // outbound content path (this was the one hole that bypassed it).
+      const new_content = redactSecrets(await resolveBareMentions(chat_id, rawNewContent));
       ws.send(JSON.stringify({
         type: "edit_message", message_id, channel_id: chat_id,
         sender_id: AGENT_ID, new_content, timestamp: new Date().toISOString(),
@@ -1760,7 +1882,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { status_text, status_emoji } = args as any;
     if (ws && ws.readyState === WebSocket.OPEN) {
       ws.send(JSON.stringify({
-        type: "set_status", sender_id: AGENT_ID, status_text, status_emoji,
+        type: "set_status", sender_id: AGENT_ID,
+        status_text: typeof status_text === "string" ? redactSecrets(status_text) : status_text,
+        status_emoji,
       }));
       return { content: [{ type: "text", text: `Status update dispatched: ${status_emoji || ''} ${status_text}` }] };
     }
@@ -1784,7 +1908,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       free_text?: string;
     };
     try {
-      const r = await fetch(`${REST_URL}/api/moderation/report`, {
+      const r = await apiFetch(`${REST_URL}/api/moderation/report`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
@@ -1799,11 +1923,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `report_message failed (${r.status}): ${text.slice(0, 240)}` }] };
+        return { content: [{ type: "text", text: `report_message failed (${r.status}): ${text.slice(0, 240)}` }], isError: true };
       }
       return { content: [{ type: "text", text }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `report_message network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `report_message network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -1812,16 +1936,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const qs = new URLSearchParams();
     if (agent_id) qs.set("agent_id", agent_id);
     try {
-      const r = await fetch(`${REST_URL}/api/me/moderation_history${qs.toString() ? `?${qs.toString()}` : ""}`, {
+      const r = await apiFetch(`${REST_URL}/api/me/moderation_history${qs.toString() ? `?${qs.toString()}` : ""}`, {
         headers: { "Authorization": `Bearer ${TOKEN}` },
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `list_my_moderation_history failed (${r.status}): ${text.slice(0, 240)}` }] };
+        return { content: [{ type: "text", text: `list_my_moderation_history failed (${r.status}): ${text.slice(0, 240)}` }], isError: true };
       }
       return { content: [{ type: "text", text }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `list_my_moderation_history network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `list_my_moderation_history network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -1829,21 +1953,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { limit = 20 } = args as { limit?: number };
     const capped = Math.max(1, Math.min(Number(limit) || 20, 100));
     try {
-      const r = await fetch(`${REST_URL}/api/me/reports_submitted?limit=${capped}`, {
+      const r = await apiFetch(`${REST_URL}/api/me/reports_submitted?limit=${capped}`, {
         headers: { "Authorization": `Bearer ${TOKEN}` },
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `list_reports_i_submitted failed (${r.status}): ${text.slice(0, 240)}` }] };
+        return { content: [{ type: "text", text: `list_reports_i_submitted failed (${r.status}): ${text.slice(0, 240)}` }], isError: true };
       }
       return { content: [{ type: "text", text }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `list_reports_i_submitted network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `list_reports_i_submitted network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
   if (name === "set_topic") {
     const { chat_id, topic } = args as any;
+    if (typeof chat_id !== "string" || typeof topic !== "string") {
+      return { content: [{ type: "text", text: "Error: chat_id and topic (strings) required" }] };
+    }
     if (ws && ws.readyState === WebSocket.OPEN) {
       ws.send(JSON.stringify({ type: "set_topic", channel_id: chat_id, sender_id: AGENT_ID, topic }));
       return { content: [{ type: "text", text: `Topic update dispatched; server may reject (admin only): ${topic.slice(0,50)}` }] };
@@ -1853,6 +1980,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
   if (name === "forward") {
     const { source_channel_id, target_channel_id, message_id } = args as any;
+    if (typeof target_channel_id !== "string" || typeof message_id !== "string") {
+      return { content: [{ type: "text", text: "Error: target_channel_id and message_id (strings) required" }] };
+    }
     if (ws && ws.readyState === WebSocket.OPEN) {
       ws.send(JSON.stringify({
         type: "forward", id: crypto.randomUUID(),
@@ -1866,10 +1996,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
   if (name === "search") {
     const { query, channel_id } = args as any;
+    if (typeof query !== "string" || query.length === 0) {
+      return { content: [{ type: "text", text: "Error: query (non-empty string) required" }] };
+    }
     try {
       const params = new URLSearchParams({ q: query, limit: "20" });
       if (channel_id) params.set("channel_id", channel_id);
-      const r = await fetch(`${REST_URL}/api/search?${params}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      const r = await apiFetch(`${REST_URL}/api/search?${params}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      if (!r.ok) {
+        return { content: [{ type: "text", text: `Search failed (${r.status})` }], isError: true };
+      }
       const data = await r.json() as any;
       if (data.messages?.length > 0) {
         const results = data.messages.map((m: any) =>
@@ -1885,6 +2021,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
   if (name === "vote") {
     const { proposal_id, decision, reason } = args as any;
+    if (typeof proposal_id !== "string" || typeof decision !== "string") {
+      return { content: [{ type: "text", text: "Error: proposal_id and decision (strings) required" }] };
+    }
     if (ws && ws.readyState === WebSocket.OPEN) {
       ws.send(JSON.stringify({
         type: "vote", proposal_id, voter_id: AGENT_ID,
@@ -1917,7 +2056,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   async function channelBrief(chatId: string): Promise<string> {
     const get = async (path: string) => {
       try {
-        const r = await fetch(`${REST_URL}${path}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+        const r = await apiFetch(`${REST_URL}${path}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
         return r.ok ? await r.json() as any : null;
       } catch { return null; }
     };
@@ -1929,8 +2068,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const memberIds: string[] = (membersData?.members || []).map((m: any) => m?.agent_id).filter(Boolean);
     let online: string[] = [];
     if (memberIds.length > 0) {
-      const pres = await get(`/api/presence?ids=${encodeURIComponent(memberIds.slice(0, 50).join(","))}`);
-      online = Object.entries(pres?.presence || {}).filter(([, v]) => v === "online").map(([k]) => k);
+      // Batch the presence query in chunks of 50 so channels with >50 members
+      // report accurately (was: memberIds.slice(0,50) — silently wrong past 50).
+      const onlineSet = new Set<string>();
+      for (let i = 0; i < memberIds.length; i += 50) {
+        const batch = memberIds.slice(i, i + 50);
+        const pres = await get(`/api/presence?ids=${encodeURIComponent(batch.join(","))}`);
+        for (const [k, v] of Object.entries(pres?.presence || {})) {
+          if (v === "online") onlineSet.add(k);
+        }
+      }
+      online = [...onlineSet];
     }
     const allDocs = docsData ? extractChannelDocsPayload(docsData) : [];
     const skills = allDocs.filter(isSkillDoc).map((d: any) => ({ doc_id: d.id, title: d.title }));
@@ -1975,7 +2123,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // Verify by checking membership
     try {
       await new Promise(r => setTimeout(r, 500)); // wait for server to process
-      const r = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/members`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      const r = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/members`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
       if (r.ok) {
         const data = await r.json() as any;
         const isMember = (data.members || []).some((m: any) => m.agent_id === AGENT_ID);
@@ -1997,12 +2145,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // fall through to WS leave_channel if REST is unreachable so existing
     // server-side WS handler still fires and updates in-memory state.
     try {
-      const r = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/leave`, {
+      const r = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/leave`, {
         method: "POST",
         headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
         body: "{}",
       });
       if (r.ok) {
+        // Prune so knownChannels / lastSeenMessageTs don't grow unbounded and
+        // turn every reconnect backfill into a serial REST fetch over channels
+        // we've already left.
+        knownChannels.delete(chat_id);
+        if (lastSeenMessageTs.delete(chat_id)) scheduleLastSeenMessageTsSave();
         const data = await r.json().catch(() => ({})) as any;
         if (data.note === "not a member") {
           return { content: [{ type: "text", text: `Already not a member of ${chat_id.slice(0, 8)}` }] };
@@ -2010,13 +2163,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return { content: [{ type: "text", text: `Left channel ${chat_id.slice(0, 8)}` }] };
       }
       if (r.status === 404) {
-        return { content: [{ type: "text", text: `Channel ${chat_id.slice(0, 8)} not found` }] };
+        return { content: [{ type: "text", text: `Channel ${chat_id.slice(0, 8)} not found` }], isError: true };
       }
       return { content: [{ type: "text", text: `Leave failed with status ${r.status}` }] };
     } catch (e: any) {
       // REST unreachable — fall back to WS leave so at least in-memory state updates
       if (ws && ws.readyState === WebSocket.OPEN) {
         try { ws.send(JSON.stringify({ type: "leave_channel", channel_id: chat_id, agent_id: AGENT_ID })); } catch {}
+        knownChannels.delete(chat_id);
+        if (lastSeenMessageTs.delete(chat_id)) scheduleLastSeenMessageTsSave();
         return { content: [{ type: "text", text: `Leave sent via WS (REST unreachable: ${String(e?.message || e).slice(0, 60)})` }] };
       }
       return { content: [{ type: "text", text: `Leave failed — no connectivity` }] };
@@ -2034,7 +2189,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (name === "hidden_identity_join") {
     const { game_id } = args as any;
     try {
-      const r = await fetch(`${REST_URL}/api/hidden-identity/games/${encodeURIComponent(game_id)}/join`, {
+      const r = await apiFetch(`${REST_URL}/api/hidden-identity/games/${encodeURIComponent(game_id)}/join`, {
         method: "POST",
         headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
         body: "{}",
@@ -2047,7 +2202,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const activeNote = channelId ? ` HI active mode enabled for channel ${String(channelId).slice(0, 8)}.` : "";
         return { content: [{ type: "text", text: `Joined game ${String(game_id).slice(0, 8)} — ${count} players in lobby.${activeNote}` }] };
       }
-      return { content: [{ type: "text", text: `Join failed (${r.status}): ${String(data?.error || "").slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `Join failed (${r.status}): ${String(data?.error || "").slice(0, 120)}` }], isError: true };
     } catch (e: any) {
       return { content: [{ type: "text", text: `Join failed: ${String(e?.message || e).slice(0, 80)}` }] };
     }
@@ -2056,7 +2211,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (name === "hidden_identity_get_secret") {
     const { game_id } = args as any;
     try {
-      const r = await fetch(`${REST_URL}/api/hidden-identity/games/${encodeURIComponent(game_id)}/secret`, {
+      const r = await apiFetch(`${REST_URL}/api/hidden-identity/games/${encodeURIComponent(game_id)}/secret`, {
         headers: { "Authorization": `Bearer ${TOKEN}` },
       });
       const data = await r.json().catch(() => ({})) as any;
@@ -2086,7 +2241,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
       if (r.status === 403) return { content: [{ type: "text", text: `You are not a player in this game (403)` }] };
       if (r.status === 404) return { content: [{ type: "text", text: `Game or secret not allocated yet (game may still be in lobby)` }] };
-      return { content: [{ type: "text", text: `Secret fetch failed (${r.status})` }] };
+      return { content: [{ type: "text", text: `Secret fetch failed (${r.status})` }], isError: true };
     } catch (e: any) {
       return { content: [{ type: "text", text: `Secret fetch failed: ${String(e?.message || e).slice(0, 80)}` }] };
     }
@@ -2097,7 +2252,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
       const body: any = { target_id };
       if (typeof reason === "string" && reason) body.reason = reason;
-      const r = await fetch(`${REST_URL}/api/hidden-identity/games/${encodeURIComponent(game_id)}/vote`, {
+      const r = await apiFetch(`${REST_URL}/api/hidden-identity/games/${encodeURIComponent(game_id)}/vote`, {
         method: "POST",
         headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
         body: JSON.stringify(body),
@@ -2106,7 +2261,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (r.ok) {
         return { content: [{ type: "text", text: `Vote cast against ${String(target_id).slice(0, 12)} in round ${data?.round}` }] };
       }
-      return { content: [{ type: "text", text: `Vote failed (${r.status}): ${String(data?.error || "").slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `Vote failed (${r.status}): ${String(data?.error || "").slice(0, 120)}` }], isError: true };
     } catch (e: any) {
       return { content: [{ type: "text", text: `Vote failed: ${String(e?.message || e).slice(0, 80)}` }] };
     }
@@ -2115,7 +2270,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (name === "hidden_identity_advance") {
     const { game_id, to } = args as any;
     try {
-      const r = await fetch(`${REST_URL}/api/hidden-identity/games/${encodeURIComponent(game_id)}/advance`, {
+      const r = await apiFetch(`${REST_URL}/api/hidden-identity/games/${encodeURIComponent(game_id)}/advance`, {
         method: "POST",
         headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
         body: JSON.stringify({ to }),
@@ -2124,8 +2279,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (r.ok) {
         return { content: [{ type: "text", text: `Phase advanced to ${data?.phase || to}, round ${data?.round ?? "?"}` }] };
       }
-      if (r.status === 409) return { content: [{ type: "text", text: `Invalid transition to ${to} (409): ${String(data?.error || "").slice(0, 120)}` }] };
-      return { content: [{ type: "text", text: `Advance failed (${r.status}): ${String(data?.error || "").slice(0, 120)}` }] };
+      if (r.status === 409) return { content: [{ type: "text", text: `Invalid transition to ${to} (409): ${String(data?.error || "").slice(0, 120)}` }], isError: true };
+      return { content: [{ type: "text", text: `Advance failed (${r.status}): ${String(data?.error || "").slice(0, 120)}` }], isError: true };
     } catch (e: any) {
       return { content: [{ type: "text", text: `Advance failed: ${String(e?.message || e).slice(0, 80)}` }] };
     }
@@ -2134,7 +2289,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (name === "hidden_identity_get_state") {
     const { game_id } = args as any;
     try {
-      const r = await fetch(`${REST_URL}/api/hidden-identity/games/${encodeURIComponent(game_id)}`, {
+      const r = await apiFetch(`${REST_URL}/api/hidden-identity/games/${encodeURIComponent(game_id)}`, {
         headers: { "Authorization": `Bearer ${TOKEN}` },
       });
       const data = await r.json().catch(() => ({})) as any;
@@ -2145,7 +2300,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }).join(", ");
         return { content: [{ type: "text", text: `Phase: ${g.phase}, Round: ${g.round}, Winner: ${g.winner_team || "—"}. Players: ${players}` }] };
       }
-      return { content: [{ type: "text", text: `Game state fetch failed (${r.status})` }] };
+      return { content: [{ type: "text", text: `Game state fetch failed (${r.status})` }], isError: true };
     } catch (e: any) {
       return { content: [{ type: "text", text: `Game state fetch failed: ${String(e?.message || e).slice(0, 80)}` }] };
     }
@@ -2153,6 +2308,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
   if (name === "mark_read") {
     const { chat_id, last_read_id } = args as any;
+    if (typeof chat_id !== "string" || typeof last_read_id !== "string") {
+      return { content: [{ type: "text", text: "Error: chat_id and last_read_id (strings) required" }] };
+    }
     if (ws && ws.readyState === WebSocket.OPEN) {
       ws.send(JSON.stringify({
         type: "read_receipt", channel_id: chat_id,
@@ -2168,7 +2326,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     let healthLine = "REST health: unknown";
     let authLine = "REST auth: unknown";
     try {
-      const r = await fetch(`${REST_URL}/health`);
+      const r = await apiFetch(`${REST_URL}/health`);
       if (r.ok) {
         const h = await r.json() as any;
         const build = h?.build ? ` build=${h.build}` : "";
@@ -2181,7 +2339,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       healthLine = `REST health: error (${String(e?.message || e).slice(0, 80)})`;
     }
     try {
-      const r = await fetch(`${REST_URL}/api/account/${encodeURIComponent(AGENT_ID)}`, {
+      const r = await apiFetch(`${REST_URL}/api/account/${encodeURIComponent(AGENT_ID)}`, {
         headers: TOKEN ? { "Authorization": `Bearer ${TOKEN}` } : {},
       });
       authLine = r.ok ? "REST auth: ok" : `REST auth: failed (${r.status})`;
@@ -2194,7 +2352,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (name === "list_channels") {
     const { limit = 50 } = args as any;
     try {
-      const r = await fetch(`${REST_URL}/api/channels/discover?limit=${Math.min(limit, 500)}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      const r = await apiFetch(`${REST_URL}/api/channels/discover?limit=${Math.max(1, Math.min(Number(limit) || 50, 500))}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
       if (r.ok) {
         const data = await r.json() as any;
         const channels = (data.channels || []);
@@ -2224,7 +2382,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       // DMs). DM channel ids are deterministic on iOS but the source of
       // truth for "does this DM exist between us" is server membership,
       // so we list + filter rather than replay the hash.
-      const r = await fetch(`${REST_URL}/api/channels/mine`, {
+      const r = await apiFetch(`${REST_URL}/api/channels/mine`, {
         headers: { "Authorization": `Bearer ${TOKEN}` },
       });
       if (!r.ok) {
@@ -2237,7 +2395,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       for (const ch of channels) {
         if (ch?.type !== "direct") continue;
         try {
-          const mr = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(ch.id)}/members`, {
+          const mr = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(ch.id)}/members`, {
             headers: { "Authorization": `Bearer ${TOKEN}` },
           });
           if (!mr.ok) continue;
@@ -2256,7 +2414,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
   if (name === "list_loops") {
     try {
-      const r = await fetch(`${REST_URL}/api/loops/mine`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      const r = await apiFetch(`${REST_URL}/api/loops/mine`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
       if (!r.ok) return { content: [{ type: "text", text: `Failed (${r.status})` }] };
       const data = await r.json() as any;
       const loops = Array.isArray(data?.loops) ? data.loops : [];
@@ -2274,7 +2432,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
   if (name === "my_entitlements") {
     try {
-      const r = await fetch(`${REST_URL}/api/me/entitlements`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      const r = await apiFetch(`${REST_URL}/api/me/entitlements`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
       if (!r.ok) return { content: [{ type: "text", text: `Failed (${r.status})` }] };
       const data = await r.json() as any;
       return { content: [{ type: "text", text: JSON.stringify(data) }] };
@@ -2293,7 +2451,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (name === "list_members") {
     const { chat_id } = args as any;
     try {
-      const r = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/members`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      const r = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/members`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
       if (r.ok) {
         const data = await r.json() as any;
         const members = data.members || [];
@@ -2310,7 +2468,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (name === "get_history") {
     const { chat_id, limit = 20 } = args as any;
     try {
-      const r = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/messages?limit=${Math.min(limit, 100)}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      const r = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/messages?limit=${Math.max(1, Math.min(Number(limit) || 20, 100))}`, { headers: { "Authorization": `Bearer ${TOKEN}` } });
       if (r.ok) {
         const data = await r.json() as any;
         const msgs = (data.messages || []).filter((m: any) => m.content !== "__typing__");
@@ -2342,13 +2500,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // Find and load the profile
     const targetFile = nameToPath(profile_name);
     if (!existsSync(targetFile)) {
-      return { content: [{ type: "text", text: `Profile "${profile_name}" not found. Available: ${available.join(", ")}` }] };
+      return { content: [{ type: "text", text: `Profile "${profile_name}" not found. Available: ${available.join(", ")}` }], isError: true };
     }
 
     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) {
@@ -2377,35 +2538,35 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const qs = new URLSearchParams();
     const normalizedLevel = normalizeChannelDocLevel(level);
     if (level !== undefined && normalizedLevel === null) {
-      return { content: [{ type: "text", text: "list_channel_docs failed: level must be 1|2|3|4" }] };
+      return { content: [{ type: "text", text: "list_channel_docs failed: level must be 1|2|3|4" }], isError: true };
     }
     if (normalizedLevel !== null) qs.set("level", String(normalizedLevel));
     const url = `${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/docs${qs.toString() ? `?${qs}` : ""}`;
     try {
-      const r = await fetch(url, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      const r = await apiFetch(url, { headers: { "Authorization": `Bearer ${TOKEN}` } });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `list_channel_docs failed (${r.status}): ${text.slice(0, 200)}` }] };
+        return { content: [{ type: "text", text: `list_channel_docs failed (${r.status}): ${text.slice(0, 200)}` }], isError: true };
       }
       return { content: [{ type: "text", text }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `list_channel_docs network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `list_channel_docs network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
   if (name === "get_channel_doc") {
     const { chat_id, doc_id } = args as { chat_id: string; doc_id: string };
     try {
-      const r = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/docs/${encodeURIComponent(doc_id)}`, {
+      const r = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/docs/${encodeURIComponent(doc_id)}`, {
         headers: { "Authorization": `Bearer ${TOKEN}` },
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `get_channel_doc failed (${r.status}): ${text.slice(0, 200)}` }] };
+        return { content: [{ type: "text", text: `get_channel_doc failed (${r.status}): ${text.slice(0, 200)}` }], isError: true };
       }
       return { content: [{ type: "text", text }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `get_channel_doc network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `get_channel_doc network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -2421,10 +2582,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     };
     const normalizedLevel = normalizeChannelDocLevel(level);
     if (normalizedLevel === null) {
-      return { content: [{ type: "text", text: "upsert_channel_doc failed: level must be 1|2|3|4" }] };
+      return { content: [{ type: "text", text: "upsert_channel_doc failed: level must be 1|2|3|4" }], isError: true };
     }
     try {
-      const r = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/docs/${encodeURIComponent(doc_id)}`, {
+      const r = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/docs/${encodeURIComponent(doc_id)}`, {
         method: "PUT",
         headers: {
           "Content-Type": "application/json",
@@ -2435,27 +2596,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `upsert_channel_doc failed (${r.status}): ${text.slice(0, 240)}` }] };
+        return { content: [{ type: "text", text: `upsert_channel_doc failed (${r.status}): ${text.slice(0, 240)}` }], isError: true };
       }
       return { content: [{ type: "text", text }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `upsert_channel_doc network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `upsert_channel_doc network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
   if (name === "list_channel_doc_revisions") {
     const { chat_id, doc_id } = args as { chat_id: string; doc_id: string };
     try {
-      const r = await fetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/docs/${encodeURIComponent(doc_id)}/revisions`, {
+      const r = await apiFetch(`${REST_URL}/api/channels/${encodeURIComponent(chat_id)}/docs/${encodeURIComponent(doc_id)}/revisions`, {
         headers: { "Authorization": `Bearer ${TOKEN}` },
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `list_channel_doc_revisions failed (${r.status}): ${text.slice(0, 200)}` }] };
+        return { content: [{ type: "text", text: `list_channel_doc_revisions failed (${r.status}): ${text.slice(0, 200)}` }], isError: true };
       }
       return { content: [{ type: "text", text }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `list_channel_doc_revisions network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `list_channel_doc_revisions network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -2463,7 +2624,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   // Maps 1:1 to the server-side routes shipped in commit 5229aab
   // (projects/AgentChat/Server/src/okr.ts + index.ts dispatch block).
   if (name === "okr_list") {
-    const { owner, status, horizon, include_archived, view, task_id } = args as { owner?: string; status?: string; horizon?: string; include_archived?: boolean; view?: string; task_id?: string };
+    const { owner, status, horizon, include_archived, view, task_id, shape, objective_id } = args as { owner?: string; status?: string; horizon?: string; include_archived?: boolean; view?: string; task_id?: string; shape?: string; objective_id?: string };
     const qs = new URLSearchParams();
     if (owner) qs.set("owner", owner);
     if (status) qs.set("status", status);
@@ -2471,17 +2632,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (include_archived) qs.set("include_archived", "true");
     if (view) qs.set("view", view);
     if (task_id) qs.set("task_id", task_id);
+    if (shape) qs.set("shape", shape);
+    if (objective_id) qs.set("objective_id", objective_id);
     const url = `${REST_URL}/api/okr/objectives${qs.toString() ? "?" + qs.toString() : ""}`;
     try {
-      const r = await fetch(url, { headers: { "Authorization": `Bearer ${TOKEN}` } });
+      const r = await apiFetch(url, { headers: { "Authorization": `Bearer ${TOKEN}` } });
       if (!r.ok) {
         const err = await r.text();
-        return { content: [{ type: "text", text: `okr_list failed (${r.status}): ${err.slice(0, 120)}` }] };
+        return { content: [{ type: "text", text: `okr_list failed (${r.status}): ${err.slice(0, 120)}` }], isError: true };
       }
       const data = await r.json() as any;
-      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `okr_list network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `okr_list network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -2495,18 +2658,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (due) body.due = due;
     if (discussion_channel_id) body.discussion_channel_id = discussion_channel_id;
     try {
-      const r = await fetch(`${REST_URL}/api/okr/objectives`, {
+      const r = await apiFetch(`${REST_URL}/api/okr/objectives`, {
         method: "POST",
         headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` },
         body: JSON.stringify(body),
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `okr_create_objective failed (${r.status}): ${text.slice(0, 160)}` }] };
+        return { content: [{ type: "text", text: `okr_create_objective failed (${r.status}): ${text.slice(0, 160)}` }], isError: true };
       }
       return { content: [{ type: "text", text: `Created: ${text}` }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `okr_create_objective network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `okr_create_objective network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -2519,18 +2682,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (Array.isArray(depends_on) && depends_on.length > 0) body.depends_on = depends_on;
     if (due) body.due = due;
     try {
-      const r = await fetch(`${REST_URL}/api/okr/objectives/${encodeURIComponent(objective_id)}/tasks`, {
+      const r = await apiFetch(`${REST_URL}/api/okr/objectives/${encodeURIComponent(objective_id)}/tasks`, {
         method: "POST",
         headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` },
         body: JSON.stringify(body),
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `okr_add_task failed (${r.status}): ${text.slice(0, 160)}` }] };
+        return { content: [{ type: "text", text: `okr_add_task failed (${r.status}): ${text.slice(0, 160)}` }], isError: true };
       }
       return { content: [{ type: "text", text: `Added: ${text}` }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `okr_add_task network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `okr_add_task network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -2544,18 +2707,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (Array.isArray(depends_on)) patch.depends_on = depends_on;
     if (due) patch.due = due;
     try {
-      const r = await fetch(`${REST_URL}/api/okr/tasks/${encodeURIComponent(task_id)}`, {
+      const r = await apiFetch(`${REST_URL}/api/okr/tasks/${encodeURIComponent(task_id)}`, {
         method: "PATCH",
         headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` },
         body: JSON.stringify(patch),
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `okr_update_task failed (${r.status}): ${text.slice(0, 160)}` }] };
+        return { content: [{ type: "text", text: `okr_update_task failed (${r.status}): ${text.slice(0, 160)}` }], isError: true };
       }
       return { content: [{ type: "text", text: `Updated: ${text}` }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `okr_update_task network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `okr_update_task network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -2563,34 +2726,34 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { task_id } = args as { task_id: string };
     const path = name === "okr_task_blockers" ? "blockers" : "blocks";
     try {
-      const r = await fetch(`${REST_URL}/api/okr/tasks/${encodeURIComponent(task_id)}/${path}`, {
+      const r = await apiFetch(`${REST_URL}/api/okr/tasks/${encodeURIComponent(task_id)}/${path}`, {
         headers: { "Authorization": `Bearer ${TOKEN}` },
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `${name} failed (${r.status}): ${text.slice(0, 160)}` }] };
+        return { content: [{ type: "text", text: `${name} failed (${r.status}): ${text.slice(0, 160)}` }], isError: true };
       }
       return { content: [{ type: "text", text }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `${name} network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `${name} network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
   if (name === "okr_open_thread") {
     const { target_type, target_id } = args as { target_type: string; target_id: string };
     try {
-      const r = await fetch(`${REST_URL}/api/okr/threads`, {
+      const r = await apiFetch(`${REST_URL}/api/okr/threads`, {
         method: "POST",
         headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` },
         body: JSON.stringify({ target_type, target_id }),
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `okr_open_thread failed (${r.status}): ${text.slice(0, 160)}` }] };
+        return { content: [{ type: "text", text: `okr_open_thread failed (${r.status}): ${text.slice(0, 160)}` }], isError: true };
       }
       return { content: [{ type: "text", text }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `okr_open_thread network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `okr_open_thread network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -2602,53 +2765,53 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (typeof current === "number") body.current = current;
     if (risk_level) body.risk_level = risk_level;
     try {
-      const r = await fetch(`${REST_URL}/api/okr/objectives/${encodeURIComponent(objective_id)}/krs`, {
+      const r = await apiFetch(`${REST_URL}/api/okr/objectives/${encodeURIComponent(objective_id)}/krs`, {
         method: "POST",
         headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` },
         body: JSON.stringify(body),
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `okr_add_kr failed (${r.status}): ${text.slice(0, 160)}` }] };
+        return { content: [{ type: "text", text: `okr_add_kr failed (${r.status}): ${text.slice(0, 160)}` }], isError: true };
       }
       return { content: [{ type: "text", text: `Added: ${text}` }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `okr_add_kr network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `okr_add_kr network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
   if (name === "archive_objective") {
     const { objective_id, completion_summary } = args as { objective_id: string; completion_summary?: string };
     try {
-      const r = await fetch(`${REST_URL}/api/okr/objectives/${encodeURIComponent(objective_id)}/archive`, {
+      const r = await apiFetch(`${REST_URL}/api/okr/objectives/${encodeURIComponent(objective_id)}/archive`, {
         method: "POST",
         headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` },
         body: JSON.stringify(completion_summary !== undefined ? { completion_summary } : {}),
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `archive_objective failed (${r.status}): ${text.slice(0, 200)}` }] };
+        return { content: [{ type: "text", text: `archive_objective failed (${r.status}): ${text.slice(0, 200)}` }], isError: true };
       }
       return { content: [{ type: "text", text: `Archived: ${text}` }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `archive_objective network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `archive_objective network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
   if (name === "unarchive_objective") {
     const { objective_id } = args as { objective_id: string };
     try {
-      const r = await fetch(`${REST_URL}/api/okr/objectives/${encodeURIComponent(objective_id)}/unarchive`, {
+      const r = await apiFetch(`${REST_URL}/api/okr/objectives/${encodeURIComponent(objective_id)}/unarchive`, {
         method: "POST",
         headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` },
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `unarchive_objective failed (${r.status}): ${text.slice(0, 200)}` }] };
+        return { content: [{ type: "text", text: `unarchive_objective failed (${r.status}): ${text.slice(0, 200)}` }], isError: true };
       }
       return { content: [{ type: "text", text: `Unarchived: ${text}` }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `unarchive_objective network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `unarchive_objective network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -2657,18 +2820,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const body: Record<string, unknown> = { current };
     if (risk_level) body.risk_level = risk_level;
     try {
-      const r = await fetch(`${REST_URL}/api/okr/krs/${encodeURIComponent(kr_id)}/progress`, {
+      const r = await apiFetch(`${REST_URL}/api/okr/krs/${encodeURIComponent(kr_id)}/progress`, {
         method: "PATCH",
         headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` },
         body: JSON.stringify(body),
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `okr_set_kr_progress failed (${r.status}): ${text.slice(0, 160)}` }] };
+        return { content: [{ type: "text", text: `okr_set_kr_progress failed (${r.status}): ${text.slice(0, 160)}` }], isError: true };
       }
       return { content: [{ type: "text", text: `Updated: ${text}` }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `okr_set_kr_progress network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `okr_set_kr_progress network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -2676,18 +2839,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { task_id, text: rawText } = args as { task_id: string; text: string };
     const text = redactSecrets(rawText);
     try {
-      const r = await fetch(`${REST_URL}/api/okr/tasks/${encodeURIComponent(task_id)}/comments`, {
+      const r = await apiFetch(`${REST_URL}/api/okr/tasks/${encodeURIComponent(task_id)}/comments`, {
         method: "POST",
         headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` },
         body: JSON.stringify({ text }),
       });
       const body = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `okr_add_task_comment failed (${r.status}): ${body.slice(0, 160)}` }] };
+        return { content: [{ type: "text", text: `okr_add_task_comment failed (${r.status}): ${body.slice(0, 160)}` }], isError: true };
       }
       return { content: [{ type: "text", text: `Commented: ${body}` }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `okr_add_task_comment network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `okr_add_task_comment network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
@@ -2708,22 +2871,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (linked_docs !== undefined) body.linked_docs = linked_docs;
     if (linked_channel_docs !== undefined) body.linked_channel_docs = linked_channel_docs;
     try {
-      const r = await fetch(`${REST_URL}/api/okr/links/${encodeURIComponent(target_type)}/${encodeURIComponent(target_id)}`, {
+      const r = await apiFetch(`${REST_URL}/api/okr/links/${encodeURIComponent(target_type)}/${encodeURIComponent(target_id)}`, {
         method: "PATCH",
         headers: { "Content-Type": "application/json", "Authorization": `Bearer ${TOKEN}` },
         body: JSON.stringify(body),
       });
       const text = await r.text();
       if (!r.ok) {
-        return { content: [{ type: "text", text: `okr_set_links failed (${r.status}): ${text.slice(0, 200)}` }] };
+        return { content: [{ type: "text", text: `okr_set_links failed (${r.status}): ${text.slice(0, 200)}` }], isError: true };
       }
       return { content: [{ type: "text", text: `Updated: ${text}` }] };
     } catch (e: any) {
-      return { content: [{ type: "text", text: `okr_set_links network error: ${String(e?.message || e).slice(0, 120)}` }] };
+      return { content: [{ type: "text", text: `okr_set_links network error: ${String(e?.message || e).slice(0, 120)}` }], isError: true };
     }
   }
 
-  return { content: [{ type: "text", text: `Unknown tool: ${name}` }] };
+  return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+  } catch (e: any) {
+    return { content: [{ type: "text", text: `${name} failed: ${String(e?.message || e).slice(0, 300)}` }], isError: true };
+  }
 });
 
 // --- WebSocket Connection ---
@@ -2733,13 +2899,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 const mentionTsFile = join(configDir, `mention-ts-${AGENT_ID}.json`);
 function loadMentionTimestamps(): Map<string, string> {
   try {
-    const raw = require("fs").readFileSync(mentionTsFile, "utf-8");
+    const raw = readFileSync(mentionTsFile, "utf-8");
     return new Map(Object.entries(JSON.parse(raw)));
   } catch { return new Map(); }
 }
 function saveMentionTimestamps(m: Map<string, string>) {
   try {
-    require("fs").writeFileSync(mentionTsFile, JSON.stringify(Object.fromEntries(m)));
+    writeFileSync(mentionTsFile, JSON.stringify(Object.fromEntries(m)));
   } catch {}
 }
 const lastMentionTimestamp = loadMentionTimestamps();
@@ -2762,13 +2928,13 @@ const lastMentionTimestamp = loadMentionTimestamps();
 const lastSeenMessageTsFile = join(configDir, `last-seen-msg-ts-${AGENT_ID}.json`);
 function loadLastSeenMessageTs(): Map<string, string> {
   try {
-    const raw = require("fs").readFileSync(lastSeenMessageTsFile, "utf-8");
+    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 {
-    require("fs").writeFileSync(lastSeenMessageTsFile, JSON.stringify(Object.fromEntries(m)));
+    writeFileSync(lastSeenMessageTsFile, JSON.stringify(Object.fromEntries(m)));
   } catch {}
 }
 const lastSeenMessageTs = loadLastSeenMessageTs();
@@ -2799,15 +2965,9 @@ function scheduleLastSeenMessageTsSave() {
   (lastSeenMessageTsTimer as any).unref?.();
 }
 
-function normalizeTimestampForCursor(ts: string | undefined, mode: "before" | "after"): string | undefined {
-  if (!ts || typeof ts !== "string") return ts;
-  const m = ts.match(/^(.*\.)(\d+)(Z)$/);
-  if (!m) return ts;
-  const frac = m[2];
-  if (frac.length >= 9) return ts;
-  const padChar = mode === "before" ? "9" : "0";
-  return m[1] + frac + padChar.repeat(9 - frac.length) + m[3];
-}
+// normalizeTimestampForCursor now lives in ./timestamps.ts (imported above),
+// where it also handles whole-second timestamps so lexical cursor comparison
+// matches chronological order.
 
 function normalizeChannelDocLevel(level: unknown): number | null {
   if (typeof level === "number" && Number.isInteger(level) && level >= 1 && level <= 4) {
@@ -2905,7 +3065,7 @@ function activateHiddenIdentityGame(gameId: string, channelId?: string) {
 
 async function fetchHiddenIdentityChannelId(gameId: string): Promise<string | undefined> {
   try {
-    const r = await fetch(`${REST_URL}/api/hidden-identity/games/${encodeURIComponent(gameId)}`, {
+    const r = await apiFetch(`${REST_URL}/api/hidden-identity/games/${encodeURIComponent(gameId)}`, {
       headers: { "Authorization": `Bearer ${TOKEN}` },
     });
     if (!r.ok) return undefined;
@@ -2951,31 +3111,22 @@ function clearFinishedHiddenIdentityGamesFromMessage(data: any) {
 // legitimately receive the same persisted message once via live WS and once
 // via REST backfill; timestamp guards alone would either fail to drop that
 // duplicate or drop older out-of-order messages that were never processed.
-const deliveredMessageIds = new Set<string>();
-const MAX_DELIVERED_MESSAGE_IDS = 5000;
+// Dedup core (key derivation + bounded set) lives in ./dedup.ts; this file
+// keeps the thin logging wrapper so call sites and stderr output are unchanged.
+const messageDedup = new MessageDedup();
 function deliverySource(data: any): string {
   return typeof data?.__source === "string" ? data.__source : "live";
 }
-function messageDedupKey(data: any): string | null {
-  if (!data || typeof data.id !== "string" || typeof data.channel_id !== "string") return null;
-  return `${data.channel_id}:${data.id}`;
-}
 function recordOrSkipDeliveredMessage(data: any): boolean {
   const key = messageDedupKey(data);
   if (!key) return false;
-  if (deliveredMessageIds.has(key)) {
+  const skip = messageDedup.recordOrSkip(key);
+  if (skip) {
     process.stderr.write(
       `[agentchat] Duplicate message skipped source=${deliverySource(data)} chat=${String(data.channel_id).slice(0, 12)} id=${String(data.id).slice(0, 12)}\n`,
     );
-    return true;
   }
-  deliveredMessageIds.add(key);
-  if (deliveredMessageIds.size > MAX_DELIVERED_MESSAGE_IDS) {
-    const arr = [...deliveredMessageIds];
-    deliveredMessageIds.clear();
-    for (const item of arr.slice(1000)) deliveredMessageIds.add(item);
-  }
-  return false;
+  return skip;
 }
 // Channels we believe we're a member of. Populated from
 // `channel_created` events on auth_ok. Used as the backfill target set.
@@ -2986,12 +3137,11 @@ const knownChannels = new Set<string>();
 let currentHandleWSMessage: ((data: any) => Promise<void>) | null = null;
 let wsReconnectAttempt = 0;
 let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-/** Flipped true when the server sends shard_moved (planned drain).
- *  ws.onclose checks + clears it so the close is treated as a clean
- *  hop, not a failure that advances the exponential backoff. */
-let isPlannedReconnect = false;
+// Tracked so shutdown / switchIdentity can cancel a pending auth_ok backfill.
+let backfillTimer: ReturnType<typeof setTimeout> | null = null;
 
 function scheduleReconnect(delayMs: number) {
+  if (shuttingDown) return; // don't resurrect the socket after shutdown
   if (reconnectTimer) clearTimeout(reconnectTimer);
   reconnectTimer = setTimeout(() => {
     reconnectTimer = null;
@@ -3024,12 +3174,29 @@ async function backfillAllChannels(): Promise<void> {
       const after = lastSeenMessageTs.get(channelId);
       const params = after ? `?after=${encodeURIComponent(after)}&limit=50` : `?limit=1`;
       const url = `${REST_URL}/api/channels/${encodeURIComponent(channelId)}/messages${params}`;
-      const res = await fetch(url, {
+      const res = await apiFetch(url, {
         headers: TOKEN ? { "Authorization": `Bearer ${TOKEN}` } : {},
       });
       if (!res.ok) continue;
       const data = await res.json() as { messages?: any[] };
       const msgs = data.messages || [];
+      // No cursor yet (cold start / freshly joined channel): DON'T replay —
+      // seed the cursor from the newest message so later backfills fetch only
+      // genuinely new messages. Replaying here would surface a possibly
+      // hours-old DM/@mention as a live notification (contract: empty cursor
+      // = no backfill).
+      if (!after) {
+        let newestTs = "";
+        for (const m of msgs) {
+          const t = String(m?.timestamp || "");
+          if (t > newestTs) newestTs = t;
+        }
+        if (newestTs) {
+          lastSeenMessageTs.set(channelId, newestTs);
+          scheduleLastSeenMessageTsSave();
+        }
+        continue;
+      }
       // Filter out self-messages upfront (faster than re-entering the
       // handler just to bail) and typing placeholders (plugin ignores
       // them anyway).
@@ -3064,17 +3231,29 @@ async function backfillAllChannels(): Promise<void> {
 }
 
 function connectWS() {
+  // Don't spin up a new socket after stdio shutdown — a stray reconnect
+  // timer must never resurrect the connection.
+  if (shuttingDown) return;
+
+  // Capture THIS socket locally. Every handler below guards on
+  // `ws !== socket`, so a superseded socket (e.g. a dead-TCP connection
+  // whose close event is delayed past the point a replacement is already
+  // live) can never clobber the current session or schedule a duplicate
+  // reconnect — the root cause of the orphan/double-connection race.
+  let socket: WebSocket;
   try {
-    ws = new WebSocket(WS_URL);
+    socket = new WebSocket(WS_URL);
+    ws = socket;
   } catch (e) {
     process.stderr.write(`[agentchat] WebSocket constructor failed: ${e}, retrying in 5s\n`);
-    setTimeout(connectWS, 5000);
+    scheduleReconnect(5000); // route through the single tracked timer
     return;
   }
 
   ws.onopen = () => {
+    if (ws !== socket) return; // superseded by a newer socket
     try {
-      ws!.send(JSON.stringify({
+      socket.send(JSON.stringify({
         type: "auth",
         agent_id: AGENT_ID,
         token: TOKEN,
@@ -3086,6 +3265,7 @@ function connectWS() {
   };
 
   ws.onmessage = async (event) => {
+    if (ws !== socket) return; // ignore late frames from a superseded socket
     let data: any;
     try { data = JSON.parse(String(event.data)); } catch { return; }
     if (data && typeof data === "object" && !data.__source) data.__source = "live";
@@ -3118,9 +3298,16 @@ function connectWS() {
       // per-channel REST fetch and re-injects each missed message
       // through handleWSMessage so @mention detection + notification
       // path is identical to live delivery — no divergent code paths.
-      setTimeout(() => { void backfillAllChannels(); }, 2000);
+      if (backfillTimer) clearTimeout(backfillTimer);
+      backfillTimer = setTimeout(() => {
+        backfillTimer = null;
+        if (!shuttingDown) void backfillAllChannels();
+      }, 2000);
     } else if (
-      data.type === "message" &&
+      // thread_reply is a bidirectional protocol frame (Server -> Client too).
+      // Route it through the same @mention / notification / cursor path as a
+      // plain message, otherwise thread @mentions are silently invisible.
+      (data.type === "message" || data.type === "thread_reply") &&
       // Loop ticks are server-fired with sender_id=loop.agent_id, which
       // equals AGENT_ID when the loop owner is THIS plugin. Without this
       // exception the outer "skip own messages" gate swallows every tick
@@ -3175,36 +3362,19 @@ function connectWS() {
       }
 
       const isDM = data.channel_id?.startsWith("dm-");
-      // Match both `@<agentId>` and `@<displayName>(<agentId>)` formats.
-      // v0.6.1 used a loose `content.includes("(" + AGENT_ID + ")")` for the
-      // second case which fired on ANY text containing `(<agentId>)` —
-      // including system messages like "User joined: name (acc_xyz)" or
-      // moderation logs. Boss msg:fc8b9b1a — codex agent received messages
-      // it wasn't @-mentioned in, ate context window. Tighten the second
-      // clause to require an `@<displayName>` immediately before `(<id>)`.
-      const idEsc = (AGENT_ID || "").replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-      const displayMentionRe = idEsc ? new RegExp(`@[^(\\n]+\\(${idEsc}\\)`) : null;
-      const isMentioned = !!(
-        data.content?.includes(`@${AGENT_ID}`) ||
-        (displayMentionRe && displayMentionRe.test(data.content || ""))
-      );
+      // Match `@<agentId>` and `@<displayName>(<agentId>)`; see matchesMention
+      // (mentions.ts) for why the second clause must not fire on incidental
+      // `(<id>)` substrings like "User joined: name (acc_xyz)".
+      const isMentioned = matchesMention(data.content || "", AGENT_ID || "");
       const activeHi = activeHiddenIdentityForChannel(data.channel_id);
 
       if (isDM || isMentioned || activeHi) {
-        // DM or @mention → respond
-        // 立即发送 typing ACK
-        if (isDM || isMentioned) {
-          try {
-            if (ws && ws.readyState === WebSocket.OPEN) {
-              ws.send(JSON.stringify({
-                type: "message", id: crypto.randomUUID(),
-                channel_id: data.channel_id, sender_id: AGENT_ID,
-                sender_type: "agent", content: "__typing__",
-                content_type: "text", timestamp: new Date().toISOString(),
-              }));
-            }
-          } catch {}
-        }
+        // DM or @mention → respond. Start a cross-pod typing heartbeat so a human
+        // on any pod sees the agent "thinking" for the whole processing duration.
+        // The hub now cross-pod-broadcasts agent typing frames (cross_pod:true)
+        // and never persists them, so this is ephemeral + zero-write. Stops when
+        // we reply to the channel (reply handler), at the 120s cap, or on shutdown.
+        if (isDM || isMentioned) startTypingHeartbeat(data.channel_id);
 
         // For @mention in channels, fetch context since last mention
         let contextPrefix = "";
@@ -3222,7 +3392,7 @@ function connectWS() {
             // membership for private). Without the Bearer header the
             // MCP agent would get 401/403 and answer the @mention
             // without any conversation context.
-            const historyRes = await fetch(historyUrl, {
+            const historyRes = await apiFetch(historyUrl, {
               headers: TOKEN ? { "Authorization": `Bearer ${TOKEN}` } : {},
             });
             if (historyRes.ok) {
@@ -3243,7 +3413,7 @@ function connectWS() {
                 const clipped = raw.length > maxPerMsg
                   ? raw.slice(0, maxPerMsg) + " …[truncated]"
                   : raw;
-                const size = clipped.length;
+                const size = Buffer.byteLength(clipped, "utf8"); // real UTF-8 bytes (CJK is 3B/char, not 1)
                 if (totalBytes + size > maxBytes) break;
                 totalBytes += size;
                 trimmed.unshift({ ...msgs[i], content: clipped });
@@ -3270,7 +3440,7 @@ function connectWS() {
           contextPrefix = `[HI游戏进行中 - 你是 game ${activeHi.gameId.slice(0, 8)} 的上桌玩家；此消息无需 @mention 也被实时推送。只在轮到你行动、需要讨论或需要投票时回复，否则可以旁观。]\n`;
         }
 
-        process.stderr.write(`[agentchat] ${isDM ? 'DM' : isMentioned ? '@mention' : 'HI-active'} from ${data.sender_id.slice(0, 8)}: ${data.content.slice(0, 50)}\n`);
+        process.stderr.write(`[agentchat] ${isDM ? 'DM' : isMentioned ? '@mention' : 'HI-active'} from ${String(data.sender_id ?? "?").slice(0, 8)}: ${String(data.content ?? "").slice(0, 50)}\n`);
 
         // 推送给 Claude Code
         try {
@@ -3294,7 +3464,7 @@ function connectWS() {
         // Channel message without @mention → silent (just log)
         rateLimitedLog(
           "silent-channel-message",
-          `[agentchat] [silent] ${data.sender_id.slice(0, 8)} in ${data.channel_id.slice(0, 12)}: ${data.content.slice(0, 30)}\n`,
+          `[agentchat] [silent] ${String(data.sender_id ?? "?").slice(0, 8)} in ${String(data.channel_id ?? "?").slice(0, 12)}: ${String(data.content ?? "").slice(0, 30)}\n`,
         );
       }
     } else if (data.type === "channel_created") {
@@ -3310,25 +3480,21 @@ function connectWS() {
       // Task #119: track channel id for reconnect backfill target set.
       if (typeof data.channel_id === "string") knownChannels.add(data.channel_id);
     } else if (data.type === "shard_moved") {
-      // Server instance shutting down or channel moved — reconnect
-      // immediately. This is a PLANNED disconnect: the server is
-      // giving us heads-up to move. Mark it so the upcoming
-      // ws.onclose doesn't treat this as a failure that increments
-      // wsReconnectAttempt / stretches the exponential backoff. When
-      // the server does a rolling deploy (several pods closing in
-      // sequence), without this flag each shard_moved would push the
-      // next reconnect 2s, 4s, 6s ... further out even though each
-      // is a clean planned event.
+      // Server instance shutting down or channel moved — a PLANNED hop.
+      // Detach the socket's onclose so it can't also run the unplanned
+      // backoff path, reset the backoff counter, and fast-reconnect. This
+      // keeps a rolling deploy (several pods closing in sequence) from
+      // pushing each successive reconnect 2s, 4s, 6s ... further out.
       process.stderr.write(`[agentchat] Shard moved, reconnecting...\n`);
       if (data.redirect_url) {
         const newUrl = data.redirect_url.replace(/^https/, "wss").replace(/^http/, "ws") + "/ws";
         process.stderr.write(`[agentchat] Redirecting to: ${newUrl}\n`);
         // Note: for simplicity we reconnect to original URL and let /api/shard handle routing
       }
-      isPlannedReconnect = true;
-      try { ws?.close(); } catch {}
+      if (ws) { ws.onclose = null; try { ws.close(); } catch {} }
       ws = null;
       sessionId = null;
+      wsReconnectAttempt = 0;
       scheduleReconnect(500);
     } else if (data.type === "error") {
       process.stderr.write(`[agentchat] Error: ${data.message}\n`);
@@ -3336,26 +3502,21 @@ function connectWS() {
   }
 
   ws.onclose = (event) => {
+    if (ws !== socket) return; // a superseded socket's delayed close — leave live state alone
     sessionId = null;
     heartbeat.resetReconnecting(); // allow heartbeat to reconnect again if needed
-    // Planned reconnect (server-initiated shard_moved): reset backoff
-    // and reconnect fast, don't count this against exponential delay.
-    if (isPlannedReconnect) {
-      isPlannedReconnect = false;
-      wsReconnectAttempt = 0;
-      // A concurrent scheduleReconnect(500) from the shard_moved
-      // handler has already been queued — don't double-schedule.
-      process.stderr.write(`[agentchat] Planned close (code=${(event as any)?.code ?? "?"}), reconnect in 0.5s\n`);
-      return;
-    }
+    // Only genuine UNPLANNED drops reach here now. Planned paths
+    // (shard_moved / heartbeat.reconnect / switchIdentity) detach this
+    // handler and self-schedule a fast reconnect, so there is no
+    // isPlannedReconnect flag to consume and no fast/slow ambiguity.
     wsReconnectAttempt++;
-    const jitter = Math.random() * 3000; // 0-3s random jitter to avoid thundering herd
-    const delay = Math.min(wsReconnectAttempt * 2, 30) * 1000 + jitter;
+    const delay = computeReconnectDelay(wsReconnectAttempt);
     process.stderr.write(`[agentchat] Disconnected (code=${(event as any)?.code ?? "?"}), reconnecting in ${Math.round(delay/100)/10}s (attempt ${wsReconnectAttempt})...\n`);
     scheduleReconnect(delay);
   };
 
   ws.onerror = (err) => {
+    if (ws !== socket) return;
     process.stderr.write(`[agentchat] WebSocket error: ${err}\n`);
   };
 }
@@ -3369,7 +3530,9 @@ const heartbeat = new HeartbeatMonitor({
   },
   reconnect: () => {
     process.stderr.write("[agentchat] Heartbeat timeout, forcing reconnect\n");
-    try { ws?.close(); } catch {}
+    // Detach onclose so the forced close doesn't also run the unplanned
+    // backoff path and downgrade this fast 500ms recovery to 2-5s.
+    if (ws) { ws.onclose = null; try { ws.close(); } catch {} }
     ws = null;
     sessionId = null;
     wsReconnectAttempt = 0; // reset backoff for heartbeat-triggered reconnect
@@ -3385,10 +3548,15 @@ function shutdownFromStdio(reason: string) {
   safeStderrWrite(`[agentchat] Stdio closed (${reason}), shutting down\n`);
   try { flushLastSeenMessageTs(); } catch {}
   try { heartbeat.stop(); } catch {}
+  try { stopAllTypingHeartbeats(); } catch {}
   if (reconnectTimer) {
     clearTimeout(reconnectTimer);
     reconnectTimer = null;
   }
+  if (backfillTimer) {
+    clearTimeout(backfillTimer);
+    backfillTimer = null;
+  }
   try { ws?.close(); } catch {}
   ws = null;
   sessionId = null;